Download - clearMDM - Settings API Instructions v1.2€¦ · The Settings API is a packaged API resource exposed via the standard Salesforce REST API. In order to authenticate to the Salesforce

clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 1

clearMDM–SettingsAPIInstructionsAuthor:MarkCane([email protected])Version:v1.2Date:18thOctober2018IntroductionThis document provides technical instructions (by example) for the deployment ofapplicationconfigurationsettingsbetweenSalesforceorgsviatheclearMDMSettingsAPI.TheSettingsAPIisRESTfulAPIthatsupportstheretrieval(GET)ofconfigurationsettingsfromasourceSalesforceorgasJSONdatathatcanbedeployed(POST)tooneormoretargetSalesforceorg.PleaseNote,theSettingsAPIisavailableinclearMDMproductversion3.7andabove.

CLEARMDM–SETTINGSAPIINSTRUCTIONS...................................................................................1

INTRODUCTION..................................................................................................................................1DOCUMENTCHANGECONTROL.............................................................................................................2APIUSECASES..................................................................................................................................2COMMITMODEL................................................................................................................................2SETTINGSAPICOVERAGE.....................................................................................................................2SETTINGSAPIPRE-REQUISITES..............................................................................................................4PERMISSIONEDUSER...................................................................................................................................4CONNECTEDAPP........................................................................................................................................4ACCESSTOKENS..........................................................................................................................................6SYSTEMSETTINGS...............................................................................................................................8SYSTEMSETTINGSRETRIEVE(GET)................................................................................................................8SYSTEMSETTINGSDEPLOY(POST)..............................................................................................................10TARGETOBJECTSETTINGS..................................................................................................................11TARGETOBJECTSETTINGSRETRIEVE(GET)...................................................................................................11TARGETOBJECTSETTINGSDEPLOY(POST)...................................................................................................13EXAMPLEAPISCENARIO....................................................................................................................14


DocumentChangeControlVersion Date Author Change1.0 9thOctober2018 MarkCane Initialversion.1.1 13thOctober2018 MarkCane APIUrlcorrections.

Picturecompressionaddedtoreducethedocumentfilesize.

1.2 18thOctober2018 MarkCane MIMEtypeconfirmationUsername=>usernamecorrectionPassword=>passwordcorrection

APIUseCasesTheSettingsAPItargetsthefollowingusecases.

• BuildAutomation.Incorporationof(clearMDM)applicationconfigurationsettingsintoautomatedbuildprocesses(ContinuousIntegration,dailybuildsetc.).

• ConfigurationManagement.Versionmanagementof(clearMDM)applicationconfigurations.Forexample,storageofversionedconfigurationsinasourcecoderepositoryalongsiderelatedSalesforcemetadata.

• Ad-hocDeployment.Convenienterror-freedeploymentofconfigurationsettingsbetweenSalesforceorgs.

WhilsttheSettingsAPIallowsapplicationconfigurationdatatomanuallymodified(viaJSONediting)andre-deployedbacktothesameSalesforceorgthispracticeisnotsupported.CommitModelApplication configuration updates applied by the Settings API will either completesuccessfullyorrollbackautomatically(onfailure)topreventapartialupdatestate.Wherefieldsreferenced(byAPIName)intheSettingsAPIJSONdonotexistinthetargetorg(ortherunninguserhasinsufficientpermissions)therelatedconfigurationsettingwillbesettoblank.TheAPIresponseerrorTextparameterwillincludethetext“MissingPermissions”andthefulllistofaffectedfieldswillberecordedintheclearMDMAuditLog(accessibleviatheAuditLogtabintheclearMDMapplication).SettingsAPICoverageAllapplicationconfigurationsettingsarecoveredbytheSettingsAPIwiththeexceptionofworkload tuning adjustments applied by clearMDM support. Please contactsupport@clearmdm.comtohavesuchsettingsappliedtonominatedSalesforceorgs.


SettingsAPIPre-requisitesPermissionedUserThe Settings API should be invoked via a Salesforce User with permissions to all fieldsreferencedbythe(clearMDM)applicationconfiguration(i.e.matchingandmergerulesetc.).TheSalesforceUsershouldalsohavethe[MDMDataSteward]PermissionSetassignedtoensurethatall(clearMDM)packagedobjectandfieldspermissionsarecorrectlyset.ConnectedAppTheSettingsAPIisapackagedAPIresourceexposedviathestandardSalesforceRESTAPI.InordertoauthenticatetotheSalesforceRESTAPI(viatheOAuth2.0protocol)aConnectedAppmustexistinboththeSourceandTargetSalesforceorgs.ForfurtherdetailsinrelationtoSalesforceRESTAPIauthenticationpleaserefertothelinkbelow.https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_understanding_authentication.htmAnexistingConnectedAppshouldbeutilisedwherepossible.PleasefollowthestepsbelowtocreateanewConnectedApp.Note,theSalesforcehelpsiteprovidesadditionaldetailsinrespecttothecreationofConnectedApps.

1. OpentheLightningAppManagerandclickthe“NewConnectedApp”button.


2. EnterthefollowinginformationontheNewConnectedApppage.

ConnectedAppField FieldValueConnectedAppName RESTAPI(aspreferred)APIName REST_API(aspreferred)ContactEmail aspreferredEnableOAuthSettings CheckedCallbackURL https://login.salesforce.com/services/oauth2/callbackSelectedOAuthScopes Accessandmanageyourdata(api)

3. SavetheNewConnectedAppviathe“Save”button.Thedetailpageshouldappearasbelow.


AccessTokensEachSettingsAPIinteraction(POSTorGET)isauthenticatedbyanAccessTokenobtainedviatheOAuth2.0Username-passwordflow.The following steps describe howanAccess Token is retrieved using the Postman1 utilityapplicationastheAPIclient.AnyRESTAPIclientcanbeutilised.

1. OpenthePostmanapplicationandcreateanewCollectiontogrouptheSettingsAPIrequestswithintheopenWorkspace.

2. CreateanewPOSTRequestnamedOAuthTokenPOST.

3. SettheURLto: https://test.salesforce.com/services/oauth2/token

4. SettheTypetoPOSTandBodyformattox-www-form-urlencoded(aspertheabove

screenshot).

1ThePostmanapplicationisusedforexamplepurposesonly;furtherdetailscanbefoundathttps://www.getpostman.com–allrightsandtrademarksrespected.


5. EntertheKeyValuepairsasdefinedbelow.

Key Valueclient_id PastetheConnectedAppConsumerKeyclient_secret PastetheConnectedAppConsumerSecretgrant_type passwordusername Salesforceusernamepassword Salesforceuserpassword+securitytoken

6. ClicktheSavebuttonandthentheSendbutton.

7. Aresponsesimilartotheexamplebelowshouldbereturned.

{

"access_token": "00D5E0000000xzY!ARYAQPk.....",

"instance_url": "https://acme--ClearMDM.cs81.my.salesforce.com",

"id": "https://test.salesforce.com/id/00D../005..",

"token_type": "Bearer",

"issued_at": "1539358891688",

"signature": "fn3KFec/v7E/1W9/..="

}

8. Theaccess_tokenandinstance_urlvaluesshouldbenotedforuseintheAPIinteractionsdescribedinthefollowingsections.

9. Note,theprocessabovemustberepeatedforeachSalesforceorgaccessedbytheSettingsAPI.


SystemSettingsTheSettingsAPIsupports2modesofsettingsretrieval;SystemSettingsandTargetObjectsettings.Theformeriscoveredinthissection.TheSystemSettingsmodecoverssettingsdisplayedontheApplicationSettingstaboftheclearMDMSettingspage.Note,retrievingSystemSettingsincludesadditionalinternalsystemsettingsthatshouldnotbemodifiedwithoutconsultationwithclearMDMsupport.SystemSettingsRetrieve(GET)The following steps describe how System Settings are retrieved using the PostmanutilityapplicationastheAPIclient.

1. CreateanewGETRequestnamedSystemSettingsGET.

2. SettheTypetoGETandtheURLtotheinstance_urlresponsevalueretrievedinthe

AccessTokenssection(point8)withthepathdefinedasbelow.{instance_url}/services/apexrest/clearmdm/1.0/SettingsData

3. SettheAuthorisationTokentotheaccess_tokenresponsevalueretrievedinthe

AccessTokenssection(point8).


4. EntertheKeyValuepairasdefinedbelow.OraddaURLparameteraspertheprior

screenshot.

Key Valuesystem all



{

"targetObject": null,

"sysSettings": {

"useMatchCyclePartitioning": false,

"selectiveUIMatchingEnabled": false,

"scheduledJobStartTimeDelaySeconds": 5,

"predictivePartitioningMode": false,

"minBlockingKeyMatchValueLength": 5,

"maxScheduledApexJobs": 100,

"maxRecordsPerIterableProcessLimit": 60000,

"maxRecordsPerIterableProcess": 30000,

"maxRecordsPerIterableCycle": 500,

"maxRecordsPerGroupFromUI": 100,

"maxRecordsPerGroup": 500,

"maxQualityRulesPerRuleSet": 20,

"maxQualityRuleSetsPerTargetObject": 10,

"maxQualityReferenceRulesPerRuleSet": 5,

"maxQualityActionsPerRuleSet": 10,

"maxPredicatesPerNonIterableProcess": 200,

"maxNormalisationRulesPerTargetObject": 10,

"maxNormalisationRefSettingRecords": 1000,

"maxMRPForManualMerge": 10,

"maxMRGMergedPerJob": 10000,

"maxMatchCyclesPerIterableCycle": 25000, ..truncated from here

}

}


SystemSettingsDeploy(POST)The following steps describe howSystemSettings are deployedusing the PostmanutilityapplicationastheAPIclient.

1. CreateanewPOSTRequestnamedSystemSettingsPOST.

2. SettheTypetoPOSTandtheURLtotheinstance_urlresponsevalueretrievedinthe




4. SettheBodyformattypetorawandthecontenttypetoapplication/json,addthetextbelowtotheBodyinputandpastethesettingsJSON(retrievedintheSettingsGETsection)tooverwritetheplaceholdertext[pasteJSONhere].Theresultshouldbecomparabletothescreenshotaboveinstructure.

{ "settingsRequest": [paste JSON here] }


6. Aresponsewhichincludestheparameter[isSuccess=True]shouldbereturned.Ifthis

isnotthecasetheclearMDMAuditLogshouldbereferencedforfurtherinformation.


TargetObjectSettingsTheSettingsAPIsupports2modesofsettingsretrieval;SystemSettingsandTargetObjectsettings.Thelatteriscoveredinthissection.TargetObjectSettingscoverallsettingsrelatedtoagivenTargetObject,namely:

• Normalisation,Matching,Synchronisation,MergeandRe-parentingSettings• DataSources• AttributeGroups• DataQualityRulesets• DataServices

AllTargetObjectsmustberetrievedanddeployedindividuallytocompletetheapplicationconfigurationdeployment.TargetObjectSettingsRetrieve(GET)The following steps describe howTargetObject Settings are retrievedusing the PostmanutilityapplicationastheAPIclient.

1. CreateanewGETRequestnamedTargetObjectSettingsGET.

2. SettheTypetoGETandtheURLtotheinstance_urlresponsevalueretrievedinthe





4. EntertheKeyValuepairasdefinedbelow.OraddaURLparameteraspertheprecedingscreenshot.

Key ValuetargetObject TheTargetObjectNamee.g.

PersonAccount



{

"targetObject": "PersonAccount",

"sysSettings": null,

"syncSettings": {

"settingName": "PersonAccount",

"lastSynchronisationDateFieldName": "clearmdm__LastSynchronisationDate__c",

"isInvokedByNormalisationJob": false,

"isActive": true

},

"reparentingSettings": {


"isResetActive": true,

"isInvokedBySynchronisationJob": false,

"isInvokedByMergeJob": true,

"isInvokedByConversionJob": false,

"isCustomRollupJobInvokedByReparentingJob": false,

"isActive": true,

"customRollupsActive": false

},

"n11nSettings": {


..truncated from here

}

}


TargetObjectSettingsDeploy(POST)The following stepsdescribehowTargetObject Settings aredeployedusing thePostmanutilityapplicationastheAPIclient.

1. CreateanewPOSTRequestnamedTargetObjectSettingsPOST.

2. SettheTypetoPOSTandtheURLtotheinstance_urlresponsevalueretrievedinthe




4. SettheBodyformattypetorawandthecontenttypetoapplication/json,addthetextbelowtotheBodyinputandpastethesettingsJSON(retrievedintheSettingsGETsection)tooverwritetheplaceholdertext[pasteJSONhere].Theresultshouldbecomparabletothescreenshotaboveinstructure.

{ "settingsRequest": [paste JSON here] }


6. Aresponsewhichincludestheparameter[isSuccess=True]shouldbereturned.Ifthis

isnotthecasetheclearMDMAuditLogshouldbereferencedforfurtherinformation.


ExampleAPIScenarioDEVsandboxtoSITsandboxdeploymentclearMDMApplicationConfiguration:

• PersonAccountTargetObject(allsettings)• SAPCustomersTargetObject(normalisationanddataqualitysettingsonly)

Steps:

1. GETSystemSettingsfromDEV.2. POSTSystemSettingstoSIT.3. GETTargetObjectSettings(SAPCustomers)fromDEV.4. POSTObjectSettings(SAPCustomers)toSIT.5. GETTargetObjectSettings(PersonAccount)fromDEV.6. POSTObjectSettings(PersonAccount)toSIT.

Between each step the clearMDMAudit Log should be checked formissing fields wheresuccessindicator(isSuccess)istruebuttheresponseerrortextissetto“MissingPermissions”.IfthesuccessindicatorisfalsetheAuditLogwilldescribetheerrorconditionthathascausedtheAPIinteractiontofail.