ZIS configs

一个集成子配置存储设置。我n most cases, the setting values are specific to a customer's account. For example, a config may contain a customer's AWS account ID or a Slack channel.

Managing configs

You manage ZIS configs in two ways:

• Using theZIS Configs API
• Using the following built-in actions in a ZIS flow:
  • LoadConfig
  • PatchConfig

我n a typical setup, a Zendesk admin specifies their integration settings using a private Zendesk app. You create this app using theZendesk Apps framework (ZAF)．应用程序使用ZIS Configs API to store the settings in a config. You can then use the built-in config actions to load or update the config in a ZIS flow.

Tip:For an example of this setup, check out theZendesk app as an admin interfacetutorial series.

Creating a config

You can create a config using the ZIS Configs API'sCreate Configurationendpoint. Requests to the endpoint require the following parameters:

• A registeredintegrationname
• Ascopestring that uniquely identifies the config
• AconfigJSON object. This object contains integration settings as arbitrary key-value pairs.

An admin typically specifies the values for theconfigobject using a configuration user interface (UI) in a Zendesk app.

For example, the following snippet contains an HTML form. This form serves as a basic config UI for a Zendesk app. The form lets admins specify the ticket priority and Slack channel settings for a Slack integration.

The snippet also imports the ZAF SDK. The SDK lets you use theZAF clientto make API requests.

             

              
<formid="form"><labelfor="priority">Ticket prioritylabel><selectid="priority"><optionvalue="low">Lowoption><optionvalue="normal">Normaloption><optionvalue="high">Highoption><optionvalue="urgent">Urgentoption>select><labelfor="channel">Slack channellabel><inputid="channel"placeholder="For example: #general"type="text"/><inputtype="submit"value="Submit"/>form>．..<scripttype="text/javascript"src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js">script>
             

The following JavaScript uses the ZAF client'srequest()method to make a Create Configuration request in a Zendesk app. The request'sconfigobject contains user input from the HTML form.

             

              
// Initializes the ZAF clientconstclient=ZAFClient．init();constintegration="my_slack_integration";client．request({type:"POST",url:"/api/services/zis/integrations/"+integration+"/configs",contentType:"application/json",data:JSON．stringify({scope:"slack_settings",config:{priority:document．getElementById("priority")．value,channel:document．getElementById("channel")．value,},}),});
             

When run, the request creates a config in the ZIS Configs Service. The config is scoped to the admin's Zendesk account and integration. Example response:

             

              
{"config":{"id":123456,"scope":"slack_settings","zendesk_account_id":12345678,"integration":"my_slack_integration","config":{"priority":"urgent","channel":"#zendesk-tickets"},"created_at":“2099 - 05 - 06 - t17:14:30z”,"updated_at":“2099 - 05 - 06 - t17:14:30z”}}
             

Fetching configs

You can use aShow Configurationrequest to look up existing configs. The request matches configs based on theintegrationandfilter[scope]parameters.

Thefilter[scope]parameter supports wildcard (*) values. For example, the following request matches configs with a scope that begins with "slack".

             

              
constclient=ZAFClient．init();constintegration="my_slack_integration";constscope="slack*";letfetched_config={};client．request({type:"GET",url:"/api/services/zis/integrations/"+integration+"/configs?filter[scope]="+scope,})．then(function(response){fetched_config=response．configs[0]．config;});
             

The response contains an array of matching configs. If the request returns multiple pages of results, you can navigate them usingcursor pagination．

             

              
{"meta":{"has_more":false},"next":null,"configs":[{"id":123456,"scope":"slack_settings","zendesk_account_id":12345678,"integration":"my_slack_integration","config":{"priority":"urgent","channel":"#zendesk-tickets"},"created_at":“2099 - 05 - 06 - t17:14:30z”,"updated_at":“2099 - 05 - 06 - t17:14:30z”},],"links":{"next":""}}
             

You can display the returned configs in a Zendesk app. The following JavaScript displays a fetched config in the HTML form fromCreating a config．

             

              
document．getElementById("priority")．value=fetched_config．priority;document．getElementById("channel")．value=fetched_config．channel;
             

Replacing a config

You can use anUpdate Configurationrequest to replace an existing config. To identify the existing config, the request requires theintegrationandscopeparameters. The request also requires a newconfigobject. This newconfigobject completely overwrites any existing settings in the config.

Note:You can't use an Update Configuration request to change a config'sscope．

             

              
constclient=ZAFClient．init();constintegration="my_slack_integration";constscope="slack_settings";client．request({type:"PUT",url:"/api/services/zis/integrations/"+integration+"/configs/"+scope,contentType:"application/json",data:JSON．stringify({config:{priority:"high",channel:"#zendesk-tickets",},}),});
             

Updating a config

You can use aMerge Configurationrequest to make partial updates to an existing config. To identify the existing config, the request requires theintegrationandscopeparameters. The request also requires aconfigobject. The request only changes settings in theconfigobject that you specify.

Note:You can't use the Merge Configuration endpoint to change a config'sscope．

For example, the following Merge Configuration request updates theprioritysetting in an existingconfigobject. The action doesn't change other settings in the object.

             

              
constclient=ZAFClient．init();constintegration="my_slack_integration";constscope="slack_settings";client．request({type:“补丁”,url:"/api/services/zis/integrations/"+integration+"/configs/"+scope,contentType:"application/json",data:JSON．stringify({config:{priority:"high",},}),});
             

Deleting a config

You can use aDelete Configurationrequest to delete an existing config. The request requires theintegrationandscopeparameters.

             

              
constclient=ZAFClient．init();constintegration="my_slack_integration";constscope="slack_settings";client．request({type:"DELETE",url:"/api/services/zis/integrations/"+integration+"/configs/"+scope,});
             

Loading a config in a ZIS flow

You can use the LoadConfig action to look up an existing config in a ZIS flow. The action identifies the config based on thescopeparameter.

Note:We recommend you provide an specific scope in thescopeparameter. Thescopeparameter supports wildcard (*) values. However, if the action matches multiple configs, it only loads the first config found. This result may be inconsistent over time.

To use the action's response in later states of the ZIS flow, specify aResultPath．

             

              
"SlackSettings.LoadConfig":{"Type":"Action","ActionName":"zis:common:action:LoadConfig","Parameters":{"scope":"slack_settings"},"ResultPath":"$.config_result","Next":"NextState"}
             

The response contains the matchingconfigobject.

             

              
{"config":{"priority":"urgent","channel":"#zendesk-tickets"}}
             

Later states of the ZIS flow can access the response from theResultPath．For example, the following state references a setting value from the config.

             

              
"PostMessageOnNewTicket":{"Type":"Action","ActionName":"zis:INTEGRATION_NAME:action:PostToSlack","Parameters":{"channelId.$":"$.config_result.channel","text.$":"$.input.ticket_event.comment.body"},"Next":"NextState"}
             

Updating a config in a ZIS flow

You can use the PatchConfig action to make partial updates to an existing config. To identify the existing config, the action requires ascopeparameter. The action also requires aconfigobject. The action only changes settings in theconfigobject that you specify.

Note: You can't use the PatchConfig action to change a config'sscope．

For example, the following state uses the PatchConfig action to update theprioritysetting in an existingconfigobject. The action doesn't change other settings in the object.

             

              
"SlackSettings.PatchConfig":{"Type":"Action","ActionName":"zis:common:action:PatchConfig","Parameters":{"scope":"slack_settings","config":{"priority":"high"}},"Next":"NextState"}
             

Best practices

• Don't store secrets in ZIS configs. Configs aren't encrypted. Depending on your integration, data in a ZIS config may be accessible in connected systems.