Templates

Apart from the generic functions and events listed above, IBM® webMethods Embed SDK also provides some specific functions and events for integrating workflow templates to your websites.

There are two approaches to integrate workflow templates to your website:

Using built-in templates
Creating custom templates

Using built-in templates

Given below is the list of functions and events used by webMethods SDK, to integrate built-in templates provided by IBM webMethods Embed, to your website:

Functions

solution.renderForm(String DOM_Selector, function callback) - requires login
This function renders the import form as specified in the object schema. It attaches the form to the specified dom selector. All events are restricted to the dom selector itself and none are attached to the global space. This function is included in the solution instance.
solution.setDeploymentDescription(string Description) (sdk-version: 2.1.44)
This function sets description for the deployment of a specific solution. If description is not set for a deployment, the description of the associated solution is applied to that deployment by default.

Sample code
```
var deploymentDescription = “Sample Deployment Description”;

solution.setDeploymentDescription(deploymentDescription || ‘’’’);
```
solution.getDeploymentDescription() (sdk-version: 2.1.44)
This function retrieves the description for the deployment of a specific solution.

Sample code
```
var deploymentDescription = solution.getDeploymentDescription();

console.log(“Solution Deployment Description:”, deploymentDescription);
```
solution.setDeploymentTags(arrayOfString Tags) (sdk-version: 2.1.44)
This function sets deployment tags for a specific solution.

Sample code
```
var deploymentTagsArray = [‘tag1’’,”tag2”,”tag3”];

solution.setDeploymentTags(deploymentTagsArray || []);
```
solution.getDeploymentTags() (sdk-version: 2.1.44)
This function retrieves the deployment tags of a specific solution.

Sample code
```
var deploymentTags = solution.getDeploymentTags(); 
```

Events

form.submit.success
This event is fired when the integration form is submitted successfully by the user. Listener is on the Solution object.
form.submit.error
This event is fired when the integration form submission throws an error. Listener is on the Solution object.
validate
This event is fired when an existing authorization or connection is tested by the user. Listener is on an Embed object.
change
This event is fired after the setValue function is called which notifies any input value in the integration form. Listener is on the Solution object.
form.ready
This event is fired after the form builder is ready to render a form. Listener is on the Solution object.
form.cancel
This event is fired after the cancel button is clicked. Listener is on the Solution object.
authCreation
This event is fired after creating an authorization or connection. Listener is on an Embed object.
errorFields
This event is fired if any field value is missing while creating deployment. Listener is on an Embed object.

Creating custom form renderer

Admins can create custom integration templates and publish them on to their website/applications. Given below is the list of functions and events used by webMethods.io SDK, to create custom solutions:

Functions

new Embed.Solution(solution_id)

Instantiates the template object of the specified template.

It returns the template object associated with the specified 'template_uid', which is required to create a new integration form. The returned object contains the details of the operations the template is required to perform, for example, fetching lookup, creating OAuth, creating deployment etc.

Sample Code:

var solution = new window.Embed.Solution(solution_uid)

solution.on(‘ready’, () => {

renderForm(solution);

})

Above solution object has a _schema key which is json schema of the form. There are following type of field which you need to handle in your custom form renderer: - String - Number - Array - Object - Boolean

Sample Code:

renderField( $div, obj ) { //$div is DOM element and obj is individual field

	switch(obj.type) {

    case "string":

        if(obj.enum) {

            $div = new SelectBox({ element: $div, schema: obj, builderRef: this })

            break; 

        }

        if((obj.hasOwnProperty('auth')  || obj.hasOwnProperty('oauth'))) {

            obj.auth = obj.auth || obj.oauth;

            $div = new AuthBox({ element: $div, schema: obj, builderRef: this })

            break;

        }

        if(obj.hasOwnProperty("connection")) {

            $div = new ConnectionBox({element : $div, schema: obj, builderRef : this});

            break;

        }

        if(obj.hasOwnProperty("lookup")){

            $div = new LookupBox({ element: $div, schema: obj, builderRef: this })

            break;

        }

        if(obj.hasOwnProperty("cloudstream_lookup")){

            $div = new CloudStreamLookupBox({element : $div, schema : obj, builderRef : this})

            break;

        }

        $div = new TextBox({ element: $div, schema: obj, builderRef: this })

        break;

    case "boolean":

        obj.hasOwnProperty('default') ?  obj.enum =  [obj.default] : null;  //[true, false];

        obj.options = {

            enumTitles : obj.enum[0] === true ? ["True"] : ["False"]

        }

        $div = new SelectBox({ element: $div, schema : obj, builderRef: this});

        break;

    case "array":

        if(obj.format === "checkbox"){

            $div = new CheckBox({element: $div, schema : obj, builderRef: this});

        }else{

            $div = new ArrayBox({ element: $div, schema: obj, builderRef: this })

        }

        break;

    case "object":

        $div = this.renderObject($div, obj, obj.keyName + "");

        break;

    case "number":

        if(obj.enum) {

            $div = new SelectBox({ element: $div, schema: obj, builderRef: this })

            break; 

        }

        $div = new TextBox({ element: $div, schema: obj, builderRef: this, typeOfField : obj.type })

        break;

    default:

        console.log("x.type is not proper")

}

}



renderObject($div, obj, parentKey) {

for(let _o in obj.properties) {

	_o.keyName = parentKey+"."+_o;

	renderField($div, _o);

}

}



ArrayBox(...) {//array field handler}

SelectBox(...) {//select field handler}

AuthBox(...){//auth field handler}

ConnectionBox(...) {//connection field handler}

LookupBox(...) {//lookup field handler}

CloudStreamLookupBox(...) {//cloudstream lookup handler}

TextBox(...) {//text field handler}

CheckBox(...) {//checkbox field handler}

solution.getFields()
Returns an array of validation fields associated with the associated object.

You can use this function to retrieve the properties and validations associated with different solution components.

Sample Code:
```
solution.getFields(); // This function returns array of object which consists of all fields in solution.
```
solution.setValue(field_name,value)
Sets a value for the specified field.

Specify the field name along with the value you want to set for that field. The ‘field_name’ details can be fetched using the ‘.getFields’ function.

Sample Code:
```
solution.setValue(‘trigger.auth’, ‘auth1234556’’); //This function will set the value of the `trigger.auth` field.
```
solution.getAuths(auth_object)
Sets a value for the specified field.

Returns an array of authorizations associated with the specified auth.

You can use this function to retrieve the list of available authorizations associated with the specified field name. The ‘auth_object’ is fetched from the solution schema field.

Sample Code:
```
solution.getAuths(auth/connection object).then((resp) => {

listUserAuths(resp)

}, (err)=> {

console.log(err)

})
```
embed.getConnectorSchema( provider)
Returns the JSON schema of the specified field or provider.

You can use this function to retrieve the complete JSON schema associated with the specified provider. The ‘provider’ can be fetched from the connector object or you can pass the object to solution.getAuthType function.

Sample Code:
```
solution.getConnectorSchema(‘pagerduty_provider’).then((resp) => {

showConnectionForm(resp)

}, (err)=> {

console.log(err)

})
```

solution.getLookupData(lookup_object, page,searchObj)

Returns the list of lookup fields associated with the specified field name.

Use this function to retrieve the list of lookup values associated with the specified field in a trigger or action. The ‘lookup_object’ is fetched from the solution schema field. When using this function in a trigger, you need to provide the ‘trigger_id’ in the parent key. If you are using this function for an action, you can leave the parent key empty.

Sample Code:

var lookupObj = {...}; //Schema of lookup field

var searchObj = {

search: 'abc',

searchid: 'abc'

}; // SearchObj is optional

var params = lookupObj.params; // You can modify the params as per your usecase.

solution.getLookupData(lookupObj, params, searchObj).then((data) => { // must pass lookupObj reference as internally SDK is using the reference of the lookupObj

//data has two keys: 1. results - list of options, 2. next_page - which contains information about next getLookupData call.

listLookupField(data);

},(err)=>{

//check if any dependent field is not met its condition

console.log(err);

})

solution.getICLookupData(lookup_object, searchString)

Returns the list of lookup fields associated with the specified field name.

Sample Code:

var lookupObj = {...}; //Schema of lookup field

var searchObj = "abc" // searchObj is optional

var params = lookupObj.params; // You can modify the params as per your usecase.

solution.getICLookupData(lookupObj, params, searchObj).then((data) => { // must pass lookupObj reference as internally SDK is using the reference of the lookupObj

//data has three keys: 1. results - list of options, 2. searchObj  3. params - next page information

listICLookupField(data);

},(err)=>{

//check if any dependent field is not met its condition

console.log(err);

})

embed.addAuth( {provider, label, scopeScreen, closeScopeScreen}, callback)
Creates a new authorization for the specified provider.

This function lets you create a new authorization for the specified provider. The ‘provider’ can be fetched from the connector object or you can pass the object to solution.getAuthType function. The ‘label’ is used to identify the created authorization and is fetched from the client side. The ‘scopeScreen’ is used to display the list of scopes and is handled by the client side. The ‘closeScopescreen’ is also handled by the client side. The ‘callback’ is fetched from the API response for auth creation request.

Sample Code
```
window.Embed.addAuth({

provider,

label,

scopes: [],

scopeModalFunction,

closeScopeModalFunction

});
```
If Oauth Popup is enabled in Embed Tenant -> Settings -> Developer Tools -> OAuth popup, it opens a new tab in new browser window and performs auth process. If it is unchecked, then auth process takes place on the current browser tab.

Once you complete the auth process, the authCreation event is fired.
Embed.addConnection(data, provider)
Creates a new connection for the specified provider.

You can use this method to create a new connection and send the connection details for the specified provider. ‘data’ is handled by client side and the ‘provider’ can be fetched from the connector object or you can pass the object to solution.getAuthType function.

Sample Code:
```
var data = { data : value,  provider : "pagerduty", version : connection_schema.version || "v1"  };

if(connection_schema.metadata ) {

data.metadata = connection_schema.metadata;

}

window.Embed.addConnection(data).then((res) => {

//Connection is created sucessfully.

//Close connection modal

}, (err) => {

console.log(err);

})
```
solution.submitForm()
Submits the integration form and creates a deployment in the background.

Submit the integration form, which creates a deployment in the background and raises either ‘form.submit.success’ or ‘form.submit.error’ event.

Sample Code:
```
solution.submitForm()
```
new Embed.solution() solution.init(deployment_id)
Updates existing integration/deployment.

You can update an integration using this function. For this you need to pass integration id in function parameter. You can extract the integration id from the response of the Embed.getMyIntegrations() or Embed.getMyDeployments()function.

Sample Code:
```
var solution = new window.Embed.Solution();

solution.init(deployment_uid)

solution.on(‘ready’, () => {

renderForm();

})
```
Above solution object has a _schema key which is json schema of the form. Also use deployment_data key for saved value.

solution.isDependencyFulfilled(lookup_obj)

Validates the dependent lookup inputs and provides necessary data to fetch lookup data.

Use this method to validate the input data for dependent lookup fields and subsequently send required parameters to send lookup request.

Sample Code:

var lookupObj = {...}; //Schema of lookup field

var params = lookupObj.params; // You can modify the params as per your usecase.

var {shouldFetch, depObj, errKey} = solution.isDependencyFulfilled(lookupObj, params);

if(!shouldFetch) {

console.log('Please select valid '+(errKey || (((lookupObj.lookup || {}).auth === "connection" ) ? 'connection' : 'authorization')));

}

solution.getAuthType(obj)
Retrieves provider and type for auth and connection.

Sample Code:
```
solution.getAuthType(obj); // Output - {provider: ‘asana’, ‘type’: ‘auth’}
```
solution.getName()
Retrieves solution name.

Sample Code:
```
solution.getName(); // Output - Solution Name
```

solution.testAuth(auth_uid)

Tests the existing authorization associated with a specific solution. This fucntion calls validate event which can be captured using Embed listener;

Sample Code:

solution.testAuth(‘auth123’);

window.Embed.on('validate', (data) => {

let output = typeof data.data === "string" ? data.data :  typeof data.data === "object" ? data.data.result : null;

if(!output){

    console.log('Invalid Response');

}

var result = "";

if(output)

    result = output === "Auth validated successfully" || output.toLowerCase() === "connection validated successfully"   ? true : false;

if(!result) {

    showNotification('error', (data.data || {}).key == 'connection' ? `Invalid connection` : `Invalid auth`, 5);

} else {

    showNotification('success', titleCaseScript(output), 5);

}

})

solution.upgradeForm()
Allows consumers to upgrade their own deployment which belongs to a different solution.
solution.generateJsonSchema() and solution.getSchema()
Returns the JSON form Object using which you can make the custom form builder.

Sample Code:
```
solution.generateJsonSchema(); // output - solution schema
```
solution.setMinLength(path, value)
Allows you to make any particular field mandatory.
- path(string): field path
- value(Number): 0 for optional, 1 for mandatory
Sample Code:
```
solution.setMinLength(‘trigger.email_field’, 1); // output - Now trigger email_field is mandatory
```
solution.getMinLength(path)
Returns whether the field is mandatory or not.

Sample Code:
```
solution.getMinLength(‘trigger.email_field’); // output - 1 or 0
```

solution.getValue(path:optional)

Returns the form value.

Sample Code:

solution.getValue(‘trigger.email_field’); // output -abc@abc.com

solution.getFieldSchema(path)
Fetches the JSON schema of the field.

Sample Code:
```
solution.getFieldSchema(‘trigger.email_field’); // output -abc@abc.com
```
solution.validate()
Returns an array of validation errors associated with the template.

It returns the details of the validations applied to the template.

Sample Code:
```
solution.validate(); // output - array of string which contains list of error fields
```
solution.setRestartDeployment(boolean checked) (sdk-version: 2.1.49)
Sets deployment restart as true/ false for the given solution.

Sample Code:
```
var restartDeploymentChecked = true;

solution.setRestartDeployment(!!restartDeploymentChecked);
```

solution.getRestartDeployment() (sdk-version: 2.1.49)

Gets restart deployment value (boolean) for the given solution.

Sample Code:

var restartDeploymentChecked = solution.getRestartDeployment();

console.log(“Solution Deployment Restart: ”, restartDeploymentChecked);

Events

IBM webMethods Embed SDK raises various events to notify the clients about its states. Event listeners can be attached and removed by using 'on' and 'off' methods.

form.submit.success
This event is fired when the integration form is submitted successfully by the user. Listener is on the Solution object.
form.submit.error
This event is fired when the integration form submission throws an error. Listener is on the Solution object.
validate
This event is fired when an existing authorization or connection is tested by the user. Listener is on an Embed object.
change
This event is fired after the setValue function is called which notifies any input value in the integration form. Listener is on the Solution object.
form.ready
This event is fired after the form builder is ready to render a form. Listener is on the Solution object.
form.cancel
This event is fired after the cancel button is clicked. Listener is on the Solution object.
authCreation
This event is fired after creating an authorization or connection. Listener is on an Embed object.
errorFields
This event is fired if any field value is missing while creating deployment. Listener is on an Embed object.

Add Custom events using below functionality:

solution.on(eventName, Function)

This creates an entry for a new event and listen for it. Pass eventName as a string in the first parameter and function as a second parameter to execute the function you need to use to fire the event.

Sample Code:

var functionCall = (data) => {console.log(data)}  // this is the function that is executed by SDK after specific event is fired.

solution.on(“eventName”, functionCall); // This line creates an event listener in the Embed object. Entry is available to view in solution._listeners key.

solution.fire(eventName, data)
This executes the event you are listening to. Pass eventName as a string in the first parameter and data that need to be used for executing the function passed while creating the event.

Sample Code:
```
var obj = { “a”: “b”, …. };

solution.fire(“eventName”, obj)
```
solution.off(eventName, Function)
This removes the entry for an event and not listen anymore for this particular event. Pass eventName as a string in the first parameter and the name of the function in the second parameter.

Sample Code:
```
Embed.off(“eventName”, functionCall) //pass reference of the function as a second parameter
```