Upload
others
View
36
Download
0
Embed Size (px)
Citation preview
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
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 2
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.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 3
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 4
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.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 5
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.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 6
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.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 7
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.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 8
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).
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 9
4. EntertheKeyValuepairasdefinedbelow.OraddaURLparameteraspertheprior
screenshot.
Key Valuesystem all
5. ClicktheSavebuttonandthentheSendbutton.
6. Aresponsesimilartotheexamplebelowshouldbereturned.
{
"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
}
}
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 10
SystemSettingsDeploy(POST)The following steps describe howSystemSettings are deployedusing the PostmanutilityapplicationastheAPIclient.
1. CreateanewPOSTRequestnamedSystemSettingsPOST.
2. SettheTypetoPOSTandtheURLtotheinstance_urlresponsevalueretrievedinthe
AccessTokenssection(point8)withthepathdefinedasbelow.{instance_url}/services/apexrest/clearmdm/1.0/SettingsData
3. SettheAuthorisationTokentotheaccess_tokenresponsevalueretrievedinthe
AccessTokenssection(point8).
4. SettheBodyformattypetorawandthecontenttypetoapplication/json,addthetextbelowtotheBodyinputandpastethesettingsJSON(retrievedintheSettingsGETsection)tooverwritetheplaceholdertext[pasteJSONhere].Theresultshouldbecomparabletothescreenshotaboveinstructure.
{ "settingsRequest": [paste JSON here] }
5. ClicktheSavebuttonandthentheSendbutton.
6. Aresponsewhichincludestheparameter[isSuccess=True]shouldbereturned.Ifthis
isnotthecasetheclearMDMAuditLogshouldbereferencedforfurtherinformation.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 11
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
AccessTokenssection(point8)withthepathdefinedasbelow.{instance_url}/services/apexrest/clearmdm/1.0/SettingsData
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 12
3. SettheAuthorisationTokentotheaccess_tokenresponsevalueretrievedinthe
AccessTokenssection(point8).
4. EntertheKeyValuepairasdefinedbelow.OraddaURLparameteraspertheprecedingscreenshot.
Key ValuetargetObject TheTargetObjectNamee.g.
PersonAccount
5. ClicktheSavebuttonandthentheSendbutton.
6. Aresponsesimilartotheexamplebelowshouldbereturned.
{
"targetObject": "PersonAccount",
"sysSettings": null,
"syncSettings": {
"settingName": "PersonAccount",
"lastSynchronisationDateFieldName": "clearmdm__LastSynchronisationDate__c",
"isInvokedByNormalisationJob": false,
"isActive": true
},
"reparentingSettings": {
"settingName": "PersonAccount",
"isResetActive": true,
"isInvokedBySynchronisationJob": false,
"isInvokedByMergeJob": true,
"isInvokedByConversionJob": false,
"isCustomRollupJobInvokedByReparentingJob": false,
"isActive": true,
"customRollupsActive": false
},
"n11nSettings": {
"settingName": "PersonAccount",
..truncated from here
}
}
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 13
TargetObjectSettingsDeploy(POST)The following stepsdescribehowTargetObject Settings aredeployedusing thePostmanutilityapplicationastheAPIclient.
1. CreateanewPOSTRequestnamedTargetObjectSettingsPOST.
2. SettheTypetoPOSTandtheURLtotheinstance_urlresponsevalueretrievedinthe
AccessTokenssection(point8)withthepathdefinedasbelow.{instance_url}/services/apexrest/clearmdm/1.0/SettingsData
3. SettheAuthorisationTokentotheaccess_tokenresponsevalueretrievedinthe
AccessTokenssection(point8).
4. SettheBodyformattypetorawandthecontenttypetoapplication/json,addthetextbelowtotheBodyinputandpastethesettingsJSON(retrievedintheSettingsGETsection)tooverwritetheplaceholdertext[pasteJSONhere].Theresultshouldbecomparabletothescreenshotaboveinstructure.
{ "settingsRequest": [paste JSON here] }
5. ClicktheSavebuttonandthentheSendbutton.
6. Aresponsewhichincludestheparameter[isSuccess=True]shouldbereturned.Ifthis
isnotthecasetheclearMDMAuditLogshouldbereferencedforfurtherinformation.
clearMDM®isaregisteredtrademarkofAudit9LtdacompanyregisteredintheUnitedKingdomwithcompanynumber08088394. 14
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.