Directly sets Attribute values, bypassing the Workflow Engine. Introduced in 11.0.30.

To perform Actions and Behaviors as well, API/WorkflowInstance/PerformStep

This API is considered experimental and is intended for internal use only at this time.

This API bypasses the Workflow Engine, which allows it to perform highly performant updates, but at the cost of increased risk of shooting yourself in the foot.

As an experimental API, the schema and feature set may change from release to release. Do not build mission-critical integrations around this API without talking to a senior technical consultant first.

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.

1 Overview
2 Logging
3 Supported Entities / Workflow types
4 Supported Attribute data types
5 Using the API
- 5.1 HTTP Request
- 5.2 HTTP Response
  - 5.2.1 Error messages

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.

Bypassing the Workflow Engine includes some trade-offs:

Pros	Cons

Pros	Cons
Highly performant	Does not perform Actions or Behaviors
Supports bulk updates in a single API call	Does not enforce Validation Rules; caller is responsible for ensuring data is valid
Updates a Workflow Instance regardless of which Step it is on	Can create issues if Attributes are updated in a way that the Workflow would not allow, and therefore does not account for
	Only supports data types that store a simple value in the `ITEM_ATTRIBUTE_VALUE` table
	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.

Since this is not considered a “Workflow operation”, some of the columns in WORKFLOW_LOG contain specific values:

.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

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

Activity Lookup
Address
Boolean
Competency Classification 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.

The key should be passed using the “apikey” authorization scheme.

Authorization: apikey xxxxxxxxxxxxxxxxx

HTTP Request

Payload is a JSON document submitted via HTTP Post.

This payload can contain multiple Attribute values to update.

[
  {
    "entityTypeAbbr": "AI",
    "wfiId": 42,
    "values": [
      { "attrDefId": 123, "val": "some new value" },
      { "attrDefId": 456, "val": "another value" },
    ]
  },
  {
    "entityTypeAbbr": "MR",
    "wfiId": 48,
    "values": [
      { "attrDefId": 555, "val": "some new value" },
      { "attrDefId": 543, "val": "another value" },
    ]
  }
]

Field	Description

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.

HTTP Response

The HTTP response is a JSON document indicating the results.

{
  "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

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.

LearningBuilder Documentation

API/WorkflowInstance/SetAttributeValues

Analytics