The MSactivator™ provides a support for PHP SDK dedicated to developing automation workflows.
Overview
This SDK provides a set of functions that can be used to call the MSactivator™ REST API and automate actions on the MSactivator™ such as create and activate managed entities, call microservice function, call processes from other workflows…
Where to find the source code of the SDK?
The SDK functions are implemented in a set of PHP files stored in the MSactivator™ container msa_dev under /opt/fmc_repository/Process/Reference/Common/Library
The PHP files are organised by API topic and contains the functions that are calling the REST API.
These functions can be called directly when implementing the tasks of the workflow processes.
Code samples
Sample implementation of a SDK PHP function
The source code below shows the implementation of one of the functions provided by the SDK.
/**
* Create Subtenant (1)
* curl -u ncroot:ubiqube -H "Content-Type: application/json" \
* -XPOST 'http://ip_address/ubi-api-rest/customer/{prefix}?name={name}&reference={reference}' -d '
{
"name": "contactName",
"firstName": "contactFirstName",
"address": {
"streetName1": "sn1",
"streetName2": "sn2",
"streetName3": "sn3",
"city": "city123",
"zipCode": "zip123",
"country": "Country098",
"fax": "1233",
"email": "contact @ company.com",
"phone": "123"
}
}
*/
function _customer_create ($operator_prefix,
$customer_name,
$external_reference = "",
$contact_details = "{}") { (2)
$msa_rest_api = "customer/{$operator_prefix}?name={$customer_name}&reference={$external_reference}";
$curl_cmd = create_msa_operation_request(OP_POST, $msa_rest_api, $contact_details); (3)
$response = perform_curl_operation($curl_cmd, "CREATE CUSTOMER"); (4)
$response = json_decode($response, true);
if ($response['wo_status'] !== ENDED) { (5)
$response = json_encode($response);
return $response;
}
$response = prepare_json_response(ENDED, ENDED_SUCCESSFULLY, $response['wo_newparams']['response_body']);
return $response;
}| 1 | A description of the function and an sample call of the matching REST API |
| 2 | The function of the SDK always starts with _ |
| 3 | Call a SDK helper function to build the curl request |
| 4 | Call a SDK helper function to execute the curl request |
| 5 | Call a SDK helper function (defined in utility.php) to format a response with proper status, comment and response payload |
Sample call of a SDK function in a workflow task.
// Create subtenant
logToFile("Creating subtenant:\n");
$customer_contact_details_array = array(); (1)
$customer_contact_details_array['firstName'] = $customer_contact_first_name;
$customer_contact_details_array['name'] = $customer_contact_name;
if (isset($context['email_recipient']) && $context['email_recipient']){
$address = array('email' => $context['email_recipient']);
$customer_contact_details_array['address'] = $address;
}
$customer_contact_details_json = json_encode($customer_contact_details_array); (2)
// Call function to create customer
$response = _customer_create ($operator_prefix, $customer_name, $customer_ext_reference,
$customer_contact_details_json); (3)
$response = json_decode($response, true); (4)
if ($response['wo_status'] !== ENDED) { (5)
$response = json_encode($response);
echo $response;
exit;
}
logToFile(debug_dump($response['wo_newparams'], "RESPONSE\n")); (6)| 1 | Build the array with the customer contact details. This parameter is defaulted by an empty array |
| 2 | Encode the array into it’s json representation |
| 3 | Call the SDK function |
| 4 | Get the JSON response as an array |
| 5 | If the call to the function failed, echo the response and exit the task |
| 6 | If the call was successful continue the task execution |
Output messages to the process execution UI
When a task runs, it is often useful to be able to provide real time message update on the UI.
The code sample below shows how to do it.
$PROCESSINSTANCEID = $context['PROCESSINSTANCEID'];
$EXECNUMBER = $context['EXECNUMBER'];
$TASKID = $context['TASKID'];
$process_params = array('PROCESSINSTANCEID' => $PROCESSINSTANCEID, (1)
'EXECNUMBER' => $EXECNUMBER,
'TASKID' => $TASKID);
update_asynchronous_task_details($process_params,
"going to sleep for ".$context['sleep']. "sec."); (2)
sleep($context['sleep']); (3)
update_asynchronous_task_details($process_params, "wakeup"); (4)| 1 | creates an array with the information about current process and task |
| 2 | update the UI with a message |
| 3 | execute some code |
| 4 | update the UI with another message |
Microservice functions
Call a microservice CREATE/UPDATE/DELETE function
$micro_service_vars_array = array (); (1)
$micro_service_vars_array ['object_id'] = $context ['id']; (2)
$micro_service_vars_array ['src_ip'] = $context ['src_ip'];
$micro_service_vars_array ['src_mask'] = $context ['src_mask'];
$micro_service_vars_array ['dst_ip'] = $context ['dst_ip'];
$micro_service_vars_array ['dst_mask'] = $context ['dst_mask'];
$micro_service_vars_array ['service'] = $context ['service'];
$micro_service_vars_array ['action'] = $context ['action'];
$object_id = $context ['id'];
$simple_firewall = array (
'simple_firewall' => array ( (3)
$object_id => $micro_service_vars_array
)
);
$response = execute_command_and_verify_response ( $managed_entity_id, CMD_CREATE, $simple_firewall, "CREATE simple_firewall" ); (4)| 1 | Build the Microservice JSON params for the CREATE operation of the microservice. |
| 2 | Assign the values passed to the workflow process to the array of parameters of the Microservice. |
| 3 | The value of the key should match the Microservice file name (stripped of the .xml file extension) |
| 4 | Call the CREATE for simple_firewall MS for each device (use CMD_UPDATE or CMD_DELETE for the other operations) |
The function execute_command_and_verify_response is defined in msa_common.php
Synchronize the managed entity configuration
The code sample below uses a PHP function from the SDK to trigger this operation by calling the IMPORT function of a microservice
$response = synchronize_objects_and_verify_response($managed_entity_id); (1)| 1 | The variable $managed_entity_id is the database ID of the managed entity |
Useful functions
Here is a list of some of the most commonly used functions.
Managed entities
Managed entity creation
function _device_create ($customer_id, $device_name, $manufacturer_id,
$model_id, $login, $password, $password_admin,
$management_address, $device_external_reference = "",
$log_enabled = "true", $log_more_enabled = "true",
$mail_alerting = "true", $reporting = "false", $snmp_community = SNMP_COMMUNITY_DEFAULT, $managementInterface = "")location: device_rest.php
| if you need to set the hostname or update the credentials you can use some dedicated functions from device_rest.php |
Managed entity activation
function _device_do_initial_provisioning_by_id ($device_id)location: device_rest.php
Managed Entity Deletion
function _device_delete ($device_id) {location: device_rest.php
Tenant and Subtenant
Tenant creation
function _operator_create ($operator_prefix, $name)location: operator_rest.php
Subtenant creation
function _customer_create ($operator_prefix, $customer_name, $external_reference = "", $contact_details = "{}")location: customer_rest.php