Defined API AAPpp Nstallatin Guide - Cherwell

Transcription

Defined API AAPppnstallatin GuideAuthored By:Douglas RobinsonFounderDefEdit Software LLC

Defined API mApp—Installation GuideTable of ContentsPurpose.3Requirements and Prerequisites.4Installing the mApp.5Installing The Defined API Windows Service.8Running the Setup Wizard.8Running the Configuration Utility.9Running the Service Installer.10Event Logging.12Cherwell Authentication / REST API Token requests.12Save Business Object Request.13Get Business Object Request.14Identify Response.15Configuring Defined API Methods / Templates.15Entering a Method Name.16Creating One-Steps To Process Defined API Requests.16Configuring the Defined API Method Action.17Configure Security Permissions.18Support.19Additional Information.19

Defined API mApp—Installation GuidePurposeThis mApp hosts a separate API that captures all requests sent to it and forwards them into your Cherwellsystem for processing within Cherwell based on API Method processing templates that you (as anadministrator) define.Using this mApp, you'll be able to define your own REST API methods along with OneSteps that are run usingthe request content and URL received by the API contained in this mApp.You'll be able to control what actions are taken, how they gather data from the request and other areas of thesystem, define many actions that take place as a result of the request, and finally also will be able to specify theresponse content for the request.This mApp consists of both a Windows Service that must be installed on an application server to host thecustomizeable API, as well as a mApp file that must be applied to your Cherwell system, which containssupporting business objects for the mApp integration.

Defined API mApp—Installation GuideRequirements and PrerequisitesTo install this mApp, you’ll need to be using a Cherwell system of Version 8.2.1 or higher, as this mApp utilizesseveral of the XML modifiers and One-Steps included in the Cherwell 8.x releases. We have not tested thismApp on lower versions of the platform, and while you may or may not be able to open / install it on thoseversions, it is not recommended. This mApp also utilizes Cherwell’s REST / Swagger API.This mApp requires hosting an additional API on port 8081. You will need to have this port opened in yourserver’s / networks firewall in order for this mApp to function properly.If you’re on SaaS – SaaS customers will need to host the windows service portion of this mApp on their ownenvironment, and it will connect up to their Cherwell system in the cloud. Performance will be impacted forSaaS customers due to the inherent delay between your local network and the SaaS system.

Defined API mApp—Installation GuideInstalling the mApp1. Open your Cherwell Administrator tool and navigate to the ‘mApps’ page.2. Click ‘Apply mApp’ and select the “Defined API.mAppz” mApp file included with this document.

Defined API mApp—Installation Guide3. Follow the prompts on the mApp installation wizard.

Defined API mApp—Installation Guide4. You should be able to advance to the mApp installation summary, and create a new Blueprint for themApp. Save the blueprint, scan, and publish.

Defined API mApp—Installation GuideInstalling The Defined API Windows ServiceYou will need to install the Defined API Windows Service on a machine on your own infrastructure to host theDefined API web service.There are three steps to setting up this windows service: Run the Setup wizard Run the Configuration utility Run the Service InstallerRunning the Setup WizardIncluded in the installation files for this mApp, you should find a ‘Setup.exe’ file.Run the Setup.exe file, and install the Defined API service.It’s important that you install the Defined API service to the default installation directory – If you changethe installation path, it may not be able to load the configuration file you define later on.

Defined API mApp—Installation GuideLeave the radio button for “Everyone” checked, and complete the installation using the “Next” buttons.Running the Configuration UtilityAfter running the setup, you’ll need to enter the configuration details for the Defined API service to connect toyour Cherwell system.Run the “Defined API Configuration.exe” file that’s been placed into the installation directory (“C:\ProgramFiles (x86)\DefEdit Software LLC\Defined API\”) by the setup wizard.

Defined API mApp—Installation GuideEnter the Cherwell URL in the following format:http://[servername or URL]Without the square brackets,with http:// at the beginning, and without a forward slash at the end.The value you’re entering here is just the root address for your cherwell server, and does not include valueslike /CherwellClient, /CherwellPortal, /CherwellAPI, etc. When needed, these values will be addedautomatically.Note: If your virtual directory for Cherwell has been changed and is not /CherwellAPI/, this mApp will notwork.Enter the Cherwell username and password that this service will authenticate with into your Cherwellenvironment. It’s recommended that this be an internal cherwell username and password.Enter a Cherwell Client API Key from your Cherwell system’s Security REST API Client settings page. Thisis necessary for our app to authenticate into the Cherwell system to record the API events that it receives.After entering the credentials and configuration information for the configuration utility, press “Save Settings”and close the configuration utility.Running the Service InstallerIn order to install and start the windows service that hosts the API for this integration, you’ll need to run the“DefinedAPI Service Installer.exe” file included in the installation directory for this mApp. This should belocated in “C:\Program Files (x86)\DefEdit Software LLC\Defined API”.Once you’ve opened the service installer, a console will appear with two options.

Defined API mApp—Installation GuideEnter the number “ 1 “ and press enter, to install the Defined API Windows Service.You will then be prompted to confirm your selection.Enter “ y “ or “ yes “ and press enter to proceed with the installation of the Defined API windows service.After this has been completed, you may press enter to close the service installer console.At this point, the Defined API service has been installed and will automatically start.Wait a few seconds for the service to initialize, and then you should be able to begin sending requests to theservice.

Defined API mApp—Installation GuideEvent LoggingBy default, the Defined API Service will log events it receives, along with pertinant troubleshootinginformation, to the Windows Application Event Log.The following events will be logged in the Application Event Log: Cherwell Authentication / REST API Token requests Save Business Object Request Get Business Object Request Identify ResponseCherwell Authentication / REST API Token requestsWhen the service receives an event, it will log into the Cherwell REST API. This logon attempt will be logged,along with the access token that was retrieved and the expiration date for that access token.

Defined API mApp—Installation GuideSave Business Object RequestAfter signing in, the service will attempt to create a business object within your Cherwell environment via theCherwell REST API / SaveBusinessObject method. You will see an event logged in the application event log forthis as well, containing the JSON that’s sent to fulfill this request in the API.If the request fails, we will use this information to troubleshoot whether there is a value that’s breaking theJSON format or causing other problems, as this information can be sent manually via a REST API client to testif the records are able to be created via the API with that information.

Defined API mApp—Installation GuideGet Business Object RequestAfter this point, the Defined API service will attempt to retrieve the contents of the business object using aGetBusinessObject REST API method. Between the Save Business Object and Get Business Object methodexecutions, Cherwell should have executed a save action / onestep on the newly saved record to execute yourdefined processing action for that REST API method. This GetBusinessObject method is intended to retrieve thevalue of the Response field, which is intended to be set to the value of the REST API response after thatonestep has completed execution.

Defined API mApp—Installation GuideIdentify ResponseThe service will then log the Response value, once found, before sending it back to the application that sent theinitial API request to the Defined API Windows Service.Configuring Defined API Methods / TemplatesIn order to use this API, you must create lookup table records under the Defined API Method table.Here, you must configure each of the following: The Method Name or the URL that triggers the configured action Create the one-step to handle the request Assign the onestep action to handle the request to this method

Defined API mApp—Installation GuideEntering a Method NameHere, you’ll configure a Method Name. The method name should map to the URL that should trigger thismethod.The method name should be formatted as the part of the URL just after the hostname, and before anyquerystring parameters.Example:API URL: http://[servername/api/cherwell?parameter1 trueIn the URL above, the Method Name to match this request would be /api/cherwell .You should not place an ending forward slash on this method name, or it will not be correctly matched.Creating One-Steps To Process Defined API RequestsBefore selecting a one-step to run for the Defined API Method, you may need to configure a onestep to execute.When creating a one-step to execute, keep in mind the following: Association when handling the API request will be Defined API Request. This is where the APIRequest is stored. Reference the image below to see how this data is captured on this request whenbuilding your onesteps:

Defined API mApp—Installation Guide The REST API content from the request will be stored in the Defined API Request object’s “APIRequest Content” field The URL for the received API Request will be stored in the Method Name field Any query string parameters included in the URL will be both: Left in the “QueryString Parameters” field Parsed and split into individual records under the Defined API Parameters relationship / Tab. Youcan easily query these within onesteps to save yourself the hassle of having to parse them manually. The RESPONSE that’s sent to each API request must be stored in the “Response” field before theonestep finishes execution.Configuring the Defined API Method ActionNext, you must configure the onestep action that’s executed when requests for this method are received.To do this, you must click on the magnifying glass icon pictured on the right of the Method Processor ActionName field, and may then select a one-step action to run.You must select a one-step action that belongs to the “Defined API Request” or “(None)” associations, asthis is the association that the execution will take place on.

Defined API mApp—Installation GuideConfigure Security PermissionsMultiple business objects included in this mApp should be restricted from your users. Promptly after installingthis mApp, open the ‘Security’ Edit Security Groups dialog in the Cherwell Administrator tool, and modifyevery non-admin security group to restrict the View, Add, Edit, and Delete access to the following businessobjects: Defined API Request Defined API MethodThe users that aren’t going to be using this mApp – Ideally any non-admin users – should not have access tothese objects, and it should be noted that if they do, then these objects may appear in the ‘New’ menu for thoseusers.It’s also recommended that you modify the Roles available in your system and hide these business objects fromany non-administrative Roles in Cherwell, to ensure they’re not visible, just in case you’ve accidentally left‘view’ or other rights on these objects and they find them via the ‘New’ menu or search menu. If users don’thave rights to these business objects, they won’t appear under any association dropdowns, table management, orthe ‘New’ menu.Uninstalling the Windows ServiceIf you attempt to uninstall the Defined API application, keep in mind you must first stop and uninstall theWindows Service using the Defined API Service Installer console application in the installation directory.If you do not do this, or it does not work, open Powershell ISE as an administrator and execute the included“Force Uninstall Script.ps1” file, which will stop and remove the service, as well as uninstalling the DefinedAPI application.

Defined API mApp—Installation GuideSupportIf you experience any issues installing this mApp, please contact DefEdit Software LLC via the contact form onour website, https://defeditsoftware.com, or by emailing doug@defeditsoftware.com directly.If you have experienced an error, please record screenshots of the error produced, as well as steps to reproduceit, to expedite any troubleshooting.General email support is provided free of charge, with no guarantee on response times or level of service.DefEdit Software LLC is owned and operated part time by Douglas Robinson, alongside another full-timeCherwell engagement. Email responses will most likely be sent after hours.Additional InformationYou may find additional information on this mApp, as well as other mApps created by DefEdit Software LLCand other useful Cherwell information on our YouTube channel.If you have a suggestion for a mApp or YouTube video you’d like to see created, please feel free to contact us.

Enter a Cherwell Client API Key from your Cherwell system’s Security REST API Client settings page. This is necessary for our app to authenticate into the Cherwell system to record the API events that it rec