Use Case: Add a New Workflow Step

In this use case, you will create a complete new workflow step that updates the Tactic Comment field with a new specified value that you will send as input.

Go to Business Object APIs tab and navigate to the “Promotion” entry. If it does not exist, create a new record with those attributes.
You need to configure the BO API Output entities. The Output entities for a BO API define which kind of objects the API works with. Since you’re working with promotions and tactics, you need to add the related ones. In the “Output Entities” related list, ensure the following entities are displayed. If not present in the related list, add them:
1. TPM_Promotion (Main promotion object wrapper)
2. TPM_Promotion.Tactic (Tactic Records)
3. TPM_Promotion.Promotion (Promotion Record)
In the workflows tab, create a new workflow with the following attributes:
1. Name: updateTacticComments
2. Description: Updates Tactic Comments with the input parameters.
Navigate to your new workflow record.
We need to configure how the input records are going to be mapped to the output records. To do so, you will add entries to the Input Entities and Mapping related list. Create the following records in the related list:
1. Record 1
  1. Business Object API Entity: Promotion
  2. Output Entity: TPM_Promotion.Promotion
  3. Input Mapping Field: Id
  4. Output Mapping Field: Id, cgcloud__ExternalId__c
2. Record 2
  1. Business Object API Entity: Tactic
  2. Output Entity: TPM_Promotion.Tactic
  3. Input Mapping Field: Id
  4. Output Mapping Field: Id, cgcloud__ExternalId__c
Add Steps into our workflow. To load all the required promotion data, you can reuse Managed Package provided workflow steps. In the Workflow Steps related list, create the following records.
1. Record 1
  1. Business Object API Workflow Step: loadPromotionDefaults(update)2
  2. Enabled: checked
  3. Sort: 10
2. Record 2
  1. Business Object API Workflow Step: loadTacticDefaults(update)2
  2. Enabled: checked
  3. Sort: 20

At this point, you’ll have a functional new API that reads the promotion and saves it. You can check the input payloads structure for this API by clicking the View Schema button on the Workflow header. The sample schema is provided below.

1{
2  "required" : [ "Id" ], // Promotion requires an Id because of the Promotion workflow step
3  "properties" : {
4    "Tactics" : {
5      "items" : {
6        "required" : [ "Id" ], // Tactic requires an Id because of the Tactic workflow step
7        "properties" : {
8          "TacticTemplate" : {
9            "pattern" : null,
10            "minLength" : null,
11            "maxLength" : 40,
12            "type" : "string"
13          },
14          "Id" : {
15            "pattern" : null,
16            "minLength" : null,
17            "maxLength" : 40,
18            "type" : "string"
19          }
20        },
21        "additionalProperties" : false,
22        "type" : "object"
23      },
24      "type" : "array"
25    },
26    "PromotionTemplate" : {
27      "pattern" : null,
28      "minLength" : null,
29      "maxLength" : 40,
30      "type" : "string"
31    },
32    "Id" : {
33      "pattern" : null,
34      "minLength" : null,
35      "maxLength" : 40,
36      "type" : "string"
37    }
38  },
39  "additionalProperties" : false,
40  "type" : "object"
41}

Add custom behavior. To add additional workflow steps, you need to create APEX classes that implement the behavior. For our example, you are going to create an APEX class that copies an input attribute from the input into the SObject Field Comment__c. Create the following APEX class in your org.

1global with sharing class SetCommentValue implements System.Callable {
2    public class SetCommentValueException extends Exception {}
3    /**
4    * This Sample Business Rule copies the value from the MyComment input attribute,
5    * into the Output Comment__c field
6    */
7    public static Object call(String method, Map<String, Object> context) {
8        // We use the context to extract variables
9        // The type of the output object is defined by it's output entity in the mapping.
10        cgcloud.TPM_Promotion.TacticRecord tactic = (cgcloud.TPM_Promotion.TacticRecord)
11            context.get('currentOutput');
12        // For input entities, it's type is always Map<String, Object>
13        Map<String, Object> input = (Map<String, Object>) context.get('currentInput');
14        
15        // Set the value to the record
16        cgcloud__Tactic__c myRecord = (cgcloud__Tactic__c) tactic.getRecord();
17        
18        myRecord.Comment__c = input.get('MyComment') != null 
19            ? String.valueOf(input.get('MyComment'))
20            : '';
21            
22        // After setting the value, you can return. The promotion and its
23        // related records will be saved
24        
25        // If any exception is thrown, no data is committed
26        return null;
27    }
28}

After creating the apex class, you need to create the BO API Workflow Step record. To do so, navigate to the Business Object API Workflow Steps tab and create a new Record.
1. Business Object API Workflow Step Name: SetCommentValue
2. Classname: SetCommentValue (Name of the APEX class)
3. Description: Sets the Comment Value for Tactic from the input attributes.
4. Method: test (Method is passed to the callable class. This way, with different methods, the same class can implement multiple behaviors)
5. Entity: Tactic (Since you want to apply this step on each Input Tactic)
6. Sales Org: 0001
After Creating the Workflow Step, you need to define which input structures the step needs. To do so, create new records in the Step Input Structures related list of the Workflow Step. Since our example uses an Attribute called MyComment, you should add a definition for it. The attributes for the Step input structures are used to determine the schema for the input. If the input does not match the schema, an error is displayed.
1. RecordType String
2. Description: New Comment Attribute value
3. Path: .MyComment
4. Required: unchecked
5. Maximum Length: 80
After creating your step input structure, you can go back to your Workflow record and add it as a Workflow Step.
1. Business Object API Workflow Step: SetCommentValue
2. Enabled: checked
3. Sort: 30

Click again on View Schema and the following is displayed.

1{
2  "required" : [ "Id" ],
3  "properties" : {
4    "Tactics" : {
5      "items" : {
6        "required" : [ "Id" ],
7        "properties" : {
8          "MyComment" : {
9            "pattern" : null,
10            "minLength" : null,
11            "maxLength" : 80,
12            "type" : "string"
13          },
14          "TacticTemplate" : {
15            "pattern" : null,
16            "minLength" : null,
17            "maxLength" : 40,
18            "type" : "string"
19          },
20          "Id" : {
21            "pattern" : null,
22            "minLength" : null,
23            "maxLength" : 40,
24            "type" : "string"
25          }
26        },
27        "additionalProperties" : false,
28        "type" : "object"
29      },
30      "type" : "array"
31    },
32    "PromotionTemplate" : {
33      "pattern" : null,
34      "minLength" : null,
35      "maxLength" : 40,
36      "type" : "string"
37    },
38    "Id" : {
39      "pattern" : null,
40      "minLength" : null,
41      "maxLength" : 40,
42      "type" : "string"
43    }
44  },
45  "additionalProperties" : false,
46  "type" : "object"
47}

Test the API by sending a request to the Promotion BO API endpoint and passing the required parameters.

POST /services/apexrest/cgcloud/promotions/ingest

1{
2  "workflow": "updateTacticComments", // Name of your workflow
3  "salesOrg": "0001",
4  "promotions": [
5    {
6      "Id": "a2VTC0000001lJR2AY",  // A promotion in the system
7      "Tactics": [
8        {
9          "Id": "a36TC0000000XYfYAM", // It's tactics
10          "MyComment": "Comment 1 - updated"
11        },
12        {
13          "Id": "a36TC0000000XYgYAM",
14          "MyComment": "Comment 2 - updated"
15        }
16      ]
17    }
18  ]
19}

After sending the request, you can track the execution status from the Business Object API Transaction Logs tab by referencing the request through the returned import Id.