Macro Integration Point

The macro integration point accepts the following POST request payload:

http://[hostName]:[portNumber]/[api-context-root]/<context-root>/macros

{
    "parameters": [
        {
            "name": "",
            "value": "" // multivalued parameters hold a comma separated list of values
        },
        {
            "name": "",
            "value": ""
        }
    ],
    "macroDefinitionCode": ""
    "requestContext": "{ "id": // Mandatory }" provided as string representation; Resembles generic api GET response structure
    or is an array,  list of records in context of macro execution given by thier id
    "requestContextList": [
        {
            "id": // Mandatory
        },
        {
            "id":
        }
    ]
}

Context for group client (nonlist) example.

{
    "requestContext": {
      "id": "" //mandatory
      "code": "",
        "displayName": "",
        "groupAccountList": [
            {
                "id": "26551"
            }
        ]
    }
}

The macro request context element must specify the object id. This is the subject id for macro history for non-list-based macros.

The subsequent steps depend on the following Macro type:

Dynamic Logic
Bulk Update
OIG Integration

Dynamic Logic

The system invokes the dynamic logic of signature Macro as the macro definition specifies. This dynamic logic takes in the parameters and context from the request and the object identified by the context id in the request (group client, group account, or group account product).

The parameter values are always interpreted as strings. A string containing commas will be converted to a list of strings.

To supply the proper object to the logic the system refers to the following:

Macro definition’s context setting.
Context element within the request.

Macro definition context setting specifies the object type - group client, group account, or group account product.

The dynamic logic allows for modifying the (context) object, such as updating contact person details. The system returns Success (201) and the following response when the dynamic logic execution starts.

Sample Response of Success

201: Created

  "links":[{
      "href" : "Task URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro history,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]
}

Suppose there is an error while executing the dynamic logic, for example, if the dynamic logic does not have the appropriate signature, the system may return one or more error messages along with the appropriate HTTP error code.

Dynamic logic based macros are recommended only for simple data manipulation requirements.

Bulk Update

The system starts bulk update activity.

The parameter list must contain all the parameters required for the bulk update activity. The system identifies the bulk update definition from the macro definition.

The response for such a macro contains an operator link with a reference to the underlying activity.

If the activity fails to start, one or more error messages are returned as given by the activity.

Sample Response of Success

201: Created

  "links":[{
      "href" : "Activity URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro address,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]
}

OIG Integration

The system starts OIG integration as specified by the property ohi.macro.{0}.endpoint. The system sends the macro request as-is, along with the details of the macro resource (rel-link subject) as the payload for OIG integration. To invoke OIG integration, it uses credentials and authentication methods for credentialKey OIG_INTEGRATION_{macrocode}.

Sample Request of Payload created by the system to start the OIG integration:

{
   "parameters":[{
    "name":"",
    "value":""  // multivalued parameters hold a comma separated list of values
     },{
    "name":"",
    "value":""
    }],
   "links": [{
      "href" : "refers to macro history",
      "rel" : "subject",
      "httpMethod" : "GET"
      }],
     "requestContext":
     {
      "id"
      "code": "",
      "displayName": "",
      "groupAccountList": [{
      "id": "26551" }]}
}

The response for such a macro contains an operator link with a reference to the underlying exchange.

Sample Response of Success

201: Created

  "links":[{
      "href" : "Exchange URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro history,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]

}

If the integration fails to start, one or more error messages are returned as given by the integration

Response

The integration point may return HTTP status codes as defined in Response Messages. If an error occurs, the appropriate HTTP status code (along with a payload containing the error details) is returned.

The following operation-specific errors can occur:

Table 1. Response Messages
Code	Severity	Message Text
OHI-IP-MRDF-001	Fatal	Macro definition code is unknown.
OHI-IP-MRDF-002	Fatal	Request context could not be parsed.
OHI-IP-MRDF-003	Fatal	Request context or request context list with a valid id element to identify the context object(s) must be specified.
OHI-IP-MRDF-004	Fatal	Either request context or request context list must be specified and not both.
OHI-IP-MRDF-005	Fatal	Request context list must be specified if the macro definition indicates it is for a list.

Access Restriction

A user authorization configuration requires access to start a macro. The relevant access restriction is macro IP and to the macro itself.

Specifying the access restriction grant of type Macro on the macro definition restricts access to the macro.