Versions Compared

Version Old Version 18 New Version 19
Changes made by

Seth Petry-Johnson

Seth Petry-Johnson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

This API only supports Extrinsic Attribute data types that store a single, simple value in the ITEM_ATTRIBUTE_VALUE table. See below for the exact list.

Intrinsic Attributes are not currently supported.

Table of Contents

Overview

This is a utility API for updating Workflow Attribute values without going through the Workflow Engine. It was designed to allow integrations to update data in LearningBuilder over an HTTP call.

...

Pros

Cons

(plus) Highly performant

(minus) Does not perform Actions or Behaviors

(plus) Supports bulk updates in a single API call

(minus) Does not enforce Validation Rules; caller is responsible for ensuring data is valid

(plus) Updates a Workflow Instance regardless of which Step it is on

(minus) Can create issues if Attributes are updated in a way that the Workflow would not allow, and therefore does not account for

(minus) Only supports data types that store a simple value in the ITEM_ATTRIBUTE_VALUE table

(minus) Currently supports Extrinsic Attributes only

Logging

A WORKFLOW_LOG entry is created for each Workflow Instance that is updated by this API, with a WORKFLOW_VALUE_LOG entry for each individual Attribute that is included in the payload.

...

.FROM_STEP_ID = 0
.FROM_STEP_NUMBER = 0
.FROM_STEP_TITLE = “** /SetAttributeValues **”
.TO_STEP_ID = 0
.TO_STEP_NUMBER = 0
.TO_STEP_TITLE = “** /SetAttributeValues **”
.ACTION_ID = 0
.ACTION_TITLE = “** /SetAttributeValues **”
.PERSON_ID = 1 (System user)
.LOGGED_IN_PERSON_ID = 1 (System user)

Supported Entities / Workflow types

The API currently supports Activity, Activity Instance, Learning Plan Instance, Member Role, and Activity Offering Attributes.

Workflow Type

Rules

Create Activity

The Workflow Instance must be Incomplete.

Complete Activity

Complete Learning Plan

Create Offering

Grant Role / Edit Role

The status of the Workflow Instance does not matter. Member Role Attributes can always be updated by this API.

Supported Attribute data types

Info

See also Workflow Attributes for the list of “Importable” data types

  • Activity Lookup

  • Address

  • Boolean

  • Competency Classification (warning) Technically importable, but not actually supported

  • Date

  • Date Time

  • Entity Image

  • Long Text

  • Member

  • Member Role

  • Multi-Select List

  • Numeric

  • PD In Focus Source

  • Pick List

  • Rating

  • Rich Text

  • Short Text

  • Tag List

  • Vimeo Source

Using the API

Calling this API requires an API Key with the SetAttributeValues permission.

...

Code Block
Authorization: apikey xxxxxxxxxxxxxxxxx

HTTP Request

Payload is a JSON document submitted via HTTP Post.

...

Field

Description

entityTypeAbbr

One of these values:

  • “AD” for Activity

  • “AI” for ActivityInstance

  • “AO” for ActivityOffering

  • “LPI” for LearningPlanInstance

  • “MR” for MemberRole

wfiId

The ID of the Workflow instance.

  • Activity - must point to an Incomplete Create Activity WFI

  • ActivityInstance - must point to an Incomplete Complete Activity WFI

  • ActivityOffering - must point to an Incomplete Create Offering WFI

  • LearningPlanInstance - must point to an Incomplete Complete LP WFI

  • MemberRole - can point to any Grant Role or Edit Role WFI, regardless of status

values

An array of attribute values to set.

values[i].attrDefId

Attribute Definition ID of the attribute to set. Must be a valid Attribute defined for the specified entity type.

values[i].val

Value to set.

Note

No validation or processing is performed on this value.

Take care when using this with data types that handle structured data, as you are responsible for correctly formatting the value in the API call.

HTTP Response

The HTTP response is a JSON document indicating the results.

Code Block
languagejson
{
  "successCount": 4,
  "errorCount": 5,
  "errors": [
    { "entityTypeAbbr": "AI", 
      "wfiId": 123, 
      "error": "entityTypeAbbr or wfi level error message",
        "values": [
          { "attrDefId": 555, "val": "some new value", "error": "attr level error message"},
          { "attrDefId": 543, "val": "another value" }
        ]   
    }
  ]
}

Error messages

Error

Reason / How to fix

Workflow Instance #{id} was not found for entity “{entityType}”

The Workflow Instance with ID matching #wfiId was either not found, or was for a different entity type than specified. Check for typos in the payload.

Workflow Instance #{id} is in a terminal state and cannot be updated

Activity, ActivityInstance, LearningPlanInstance, and ActivityOffering Attributes can only be updated if wfiId points to a Workflow Instance with “Incomplete” status. Recall the Workflow to an editable step and try again.

Attribute Definition #{id} does not exist for entity “{entityType}”

The Attribute Definition Id is not defined for the specified entity type. Check for typos in the payload.

Attribute Definition #{id} is an Intrinsic Attribute and is not supported

This API currently only supports Extrinsic Attributes.

Attribute Definition #{id} is a {type} and is not importable by this API

This API can only populate Attributes that are supported by the Workflow Import Queue, which are marked as [Importable]

An unexpected error occurred while updating the record.

An unspecified error occurred. Try again to check for a temporary or transient issue, but if it continues to fail reach out to support for assistance.