Custom Attributes and Schemas

A worktype can have a schema for custom fields so that a customer can define additional properties that are necessary to process workitems of that worktype. You must first define a jsonschema based schema. Worktypes have a schemaId property that can be used to reference a schema. You can associate your schema with your worktype by setting the schemaId property when creating a new worktype or updating an existing worktype. A worktype also has a schemaVersion property. schemaId and schemaVersion are both optional. If a schemaId is set but not a schemaVersion, it means that the latest schema version will be used when creating a workitem. Once a schemaId for a worktype is set it cannot be changed, however, the schemaVersion can be changed.

A workitem also has schemaId and schemaVersion attributes. A workitem gets its schemaId from its worktype when it is created. It also gets the schemaVersion from the worktype if there is one defined. If a workitem does not have one defined, the latest schema version available at the time of workitem creation will be the schemaVersion. Neither schemaId nor schemaVersion for a workitem can be changed. If there is no worktype schemaId at the time of workitem creation, that workitem cannot have a schemaId set via patch/update since a workitem's schemaId is only assigned at creation time.

When you update the custom attributes of a workitem, it will either update the value if the field name already exists or create a new attribute if the field name is new.

The following are permissions that are associated with the schema APIs

• Workitems > Workitem Schema > Add, Delete, Edit, View

Steps to create a workitem with custom attributes:

1. Create a schema.

{
  "name": "Schema for custom attributes",
  "version": 1,
  "enabled": true,
  "appliesTo": [
        "WORKITEM"
      ],
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Schema for custom attributes",
    "properties": {
      "custom_atrribute_text": {
        "allOf": [
          {
            "$ref": "#/definitions/text"
          }
        ],
        "title": "custom_atrribute",
        "description": "Custom attribute for text",
        "minLength": 0,
        "maxLength": 50
      },
      "custom_attribute_2_integer": {
        "allOf": [
          {
            "$ref": "#/definitions/integer"
          }
        ],
        "title": "custom_attribute_2",
        "minimum": 1,
        "maximum": 1000
      }
    }
  }
}

The required fields are

• "jsonSchema - Required; JSON representing the schema to be created.
• "$schema - Required; must be "http://json-schema.org/draft-04/schema#". JSON Schemas use a special vocabulary to annotate and validate JSON documents. See JSON Schema for more information.

Specifying the consultant information is done in the jsonSchema.properties object. Some common properties of note for individual field definitions are:

• "title" - Required; suitable for rendering as a prompt for the custom field
• "description" - not required; a brief description of the custom field
• "allOf" - Required; a reference to a core type. The value is always of the form "allOf": [ { "$ref": "#/definitions/...core type name..."}]. Allowable core type names are
• text - a string-valued field up to 100 characters in length
• longtext - a string-valued field up to 1000 characters in length
• url - A single-line string containing a URL up to 200 character in length
• identifier - A single-line string identifier up to 100 characters in length
• enum - A string value selected from a list of up to 50 unique strings, each of which is a maximum of 100 characters in length
• date - An ISO-8601 date with format YYYY-MM-DD
• datetime - An ISO-8601 GMT date and time of format YYYY-MM-DDTHH:mm:ss.sssZ
• integer - An integer whose magnitude is bounded by -2147483648 to 2147483647
• number - A decimal number whose magnitude is bounded by -9223372036854776000 to 9223372036854776000
• checkbox - Represents a selection toggle that can be in one of three states: true, false, or null (unset)
• tag - A unique set of no more than 10 no-whitespace-embedded alphanumeric string values, each of which is no longer than 100 characters

2. Create a worktype with the newly created schema.

{
   "name": "Worktype with Schema",
   "defaultWorkbinId": "a5a7145c-06bc-46c5-b6a2-c051d603351d",
   "assignmentEnabled": true,
   "divisionId": "762a7453-787e-4672-bbd8-cce0c3b8883b",
   "disableDefaultStatusCreation": false,
   "schemaId": "78c614e5-61a0-4c31-af77-aeab42a20fea"
}

Note schemaId is mandatory while schemaVersion is an optional field while creating a worktype which supports customFields. If schemaVersion is not provided while creating a worktype, workitems created from that worktypes schemaVersion will be set to the latest available version of schema at the time of workitem creation.

3. Create a workitem with custom fields.

{
   "name": "Workitem with custom attributes",
   "autoStatusTransition": true,
   "typeId": "c6a6e2c5-7c3e-40fb-9666-bbcda2496cb2",
   "customFields" : {
    "custom_attribute_text":"Text for custom attribute",
    "custom_attribute_2_integer":100
   }
}

Some rules to be aware of:

1. A worktype can be created with a schema by specifying the schemaId. Workitems created from this worktype will inherit the schemaId. The schemaId of a worktype cannot be changed.
• An exception to this update rule is if a worktype was created without a schemaId (i.e null). Once it is set, it cannot be updated.
2. A worktype can be created with a specific version of a schema by specifying both the schemaId and schemaVersion. Workitems created from this worktype will inherit both the schemaId and schemaVersion. Unlike schemaId, the schemaVersion of the worktype can be changed. Updating the schemaVersion of the worktype will not affect existing workitems of the worktype. If schemaVersion is not specified, workitems created will inherit the latest version of the schema.
3. schemaId and schemaVersion of workitems cannot be manually set, they can only be inherited from the worktype. As mentioned above, they also cannot be updated as updating the worktype will not affect existing workitems.
4. If a workitem is created from a worktype that does not have the schemaId set, it is not possible to set customFields for that workitem. Even if the schemaId is later set for the worktype, it is not possible to modify the customFields of an already created workitem. Only new workitems created after setting the schemaId on the worktype can have their customFields set.

1. Once a field has been created, it cannot be deleted. They can only be added/edited and/or disabled.
2. A field's type or name cannot be changed.
3. Field names must include the name of a core type. They must be of the form ${fieldname}_{$fieldType}. The field name must be ASCII alphanumeric. The field type must match one of the core types described in the Core Types section. Examples: startDate_date; skills_tag; certificate_longtext
4. Min/Max can only be updated so that they do not violate any data that already exists. For example, reducing a maxLength of a text field from 50 to 10 is not allowed as it "narrows" the field. The maxLength can only be increased and the minLength can only be decreased as to "widen" the field. The following error message will be returned:

{
    "message": "Invalid data schema update",
    "code": "dynamic.schema.incompatible.json.schema.update",
    "status": 400,
    "contextId": "ac23a82b-3f46-4732-a2f8-db807b1235a7",
    "details": [
        {
            "errorCode": "new.maximum.value.invalid",
            "fieldName": "jsonSchema.properties.custom_attribute_text.maxLength"
        }
    ],
    "errors": []
}

A schema can be disabled by setting the enabled property to false. This will create a new version of a schema. Only the latest version of a schema can be disabled. Schemas can be disabled anytime.

{
  "name": "Schema for custom attributes",
  "id": "78c614e5-61a0-4c31-af77-aeab42a20fea",
  "version": 1,
  "enabled": false,
  "appliesTo": [
        "WORKITEM"
      ],
  ...
}

Rules on disabled schemas:

1. Worktypes can be created (with schemaVersion & schemaId) and updated (only schemaVersion) regardless of whether or not the schema or latest schema version is disabled.
2. Workitems can only be created with customFields if the schema on the worktype is enabled and said schema's latest version is enabled.
3. CustomFields of a workitem can always be updated without regards to the enabled property of the schema or latest version of the schema.

Fields added cannot be deleted, but they can be disabled by setting _disabled to true.

{
  "name": "Schema for custom attributes",
  "id": "78c614e5-61a0-4c31-af77-aeab42a20fea",
  "version": 1,
  "enabled": false,
  "appliesTo": [
        "WORKITEM"
      ],
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "A Test Schema",
    "description": "",
    "properties": {
      "aaa_text": {
        "title": "aaa",
        "minLength": 0,
        "maxLength": 100,
        "allOf": [
          {
            "$ref": "#/definitions/text"
          }
        ],
        "_disabled": true
      }
    }
  }
}

Custom fields can also be renabled by setting _disabled to false:

{
  "name": "Schema for custom attributes",
  "id": "78c614e5-61a0-4c31-af77-aeab42a20fea",
  "version": 1,
  "enabled": false,
  "appliesTo": [
        "WORKITEM"
      ],
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "A Test Schema",
    "description": "",
    "properties": {
      "aaa_text": {
        "title": "aaa",
        "minLength": 0,
        "maxLength": 100,
        "allOf": [
          {
            "$ref": "#/definitions/text"
          }
        ],
        "_disabled": false
      }
    }
  }
}

Rules on disabled fields:

1. Disabled fields are specific to each version. If the field is disabled on the version of a schema being used, workitems cannot be created with that field.

To mark a schema for deletion, you can soft delete the schema. This is achieved by setting deleted to true which marks the schema as deleted, but the schema is still in the database.

• A new version is created where deleted is true.
• This schema and all its versions can still be used, but can no longer be updated.
• Create and update rules for worktypes and workitems remain unchanged. Even the latest "deleted" version can still be used.

DELETE /api/v2/taskmanagement/workitems/schemas/{id}?hardDelete=false

Response

{
"id": "afc6ebb3-74bb-47dd-afb8-f93df65f7373",
"name": "Schema for custom attributes",
"version": 6,
"appliesTo": [
  "WORKITEM"
],
"enabled": false,
"deleted": true,
"createdBy": {
  "id": "54e3b8f1-cfac-41f8-8da6-67fb19233748",
  "selfUri": "/api/v2/users/54e3b8f1-cfac-41f8-8da6-67fb19233748"
},
...
}

Error response when trying to update this particular schema:

{
  "message": "The schema, afc6ebb3-74bb-47dd-afb8-f93df65f7373, is deleted and can no longer be updated",
  "code": "bad.request",
  "status": 400,
  "contextId": "67894aa6-4a37-4165-b1af-b63f90b6dda7",
  "details": [],
  "errors": []
}

Note that you can mark schemas for deletion even if they are currently being used.

Information about Task Management limits can be found at this page.

1. An organization can have a maximum of 100 schemas. Disabled schemas and schemas marked for deletion count towards this limit. See limit workitem.schemas.max.
2. A schema can only have a maximum of 50 customFields. Disabled fields count towards this limit. See limit workitem.schema.fields.max.