Working with Step Data Fields

Introduction

When you create a Matter based on an existing Matter Type you automatically inherit any defined workflow template associated with that Matter Type. And in the same way you can attach Custom Data Fields to Matters and Participants (contacts), you can also attach Custom Data Fields to individual steps in a workflow. In fact, Step Data Fields are just references to existing Custom Data Fields. Using the API you can retrieve the value of Step Data Fields using the stepdatafields endpoint and set initial values with the actioncreate endpoint.

Defining Step Data Fields

To define Step Data Fields for a Matter Type you use the Actionstep web interface. From the Home page navigate to Admin -> Matter Types and select the Matter Type for which you want to define Step Data Fields in the workflow. You then click on the Workflow menu option.

On the right hand side of the page you will see a list of the Steps defined for the workflow. Clicking on one of the Steps displays the Edit workflow step page. This displays a whole collection of settings for the workflow step. If you scroll to the bottom of the page you will find a section named Custom data. Here you will see the list of Step Data Fields associated with the Matter Type and an Add data field button. The Add data field button displays the Link data field to step dialog page.

This page is used to link an existing Custom Data Field to a Step Data Field. Clicking on the Data field dropdown list displays the list of individual fields (and their parent collections) from which to select the required field.

Using the stepdatafields Endpoint

Before you can specify a default value for a Step Data Field when calling the actioncreate endpoint, you first need to obtain its unique identifier. The example below shows a fragment from the response returning all Step Data Fields for the Matter Type whose id is 7 (the Matter Type id can be obtained from calling the actiontypes endpoint).

GET {{api_endpoint}}/api/rest/stepdatafields?actionType=7

...
{
    "id": 20,
    "groupLabel": "Matter Info",
    "fieldLabel": "Client Requirements",
    "fieldDescription": "Description of client requirements, complaint, charges, etc",
    "defaultValue": null,
    "forceDefaultValue": "F",
    "displayOrder": 30,
    "isRequired": "F",
    "links": {
        "actionType": "7",
        "step": "7--1",
        "dataCollection": "data_collection_id",
        "dataField": "19--client_requirements"
    }
}
...

In the response you will see the "id" property is 20. This is the unique identifier for this particular Step Data Field. You can also see the dataField property under links section with a value of "19--client_requirements". This is the unique id for the underling Custom Data Field from which the Step Data Field is derived. You can view the details of the underlying Custom Data Field by using the dataField property as shown below:

GET {{api_endpoint}}/api/rest/datacollectionfields/19--client_requirements

...
"datacollectionfields": {
    "id": "19--client_requirements",
    "name": "client_requirements",
    "dataType": "TextArea",
    "label": "Client Requirements",
    "formOrder": 10,
    "listOrder": 10,
    "required": "F",
    "description": "Description of client requirements, complaint, charges, etc",
    "customHtmlBelow": null,
    "customHtmlAbove": null,
    "links": {
        "dataCollection": "19",
        "tag": null
    }
}
...

Setting a Step Data Field Value with the actioncreate Endpoint

Having obtained the unique indentifier for the Step Data Field (20 in the example above), you can now set its value when you create a Matter using the actioncreate endpoint.

POST {{api_endpoint}}/api/rest/actioncreate/7

{
  "actioncreate": {
    "actionName": "Test Matter",
    "stepDataField20": "Just a reminder this is a fixed fee matter as agreed with the client.",
    "links": {
      "actionType": "7"
    }
  }
}

From the example above you can see the inclusion of the stepDataField20 property in the request message body. The name of this property is composed from the prefix text "stepDataField" concatenated with the unique id for the Step Data Field. You also include a value for the field in accordance with the field's underlying data type. When you view the Matter using the Actionstep web interface you will be able to view the Step Data Field value you supplied in the API request to the actioncreate endpoint.