URL Linking

Hyperlinks or buttons can be made available in external CRM or content management systems to invoke information request forms on ManageMyRequests, passing customer details to the form. Once a case exists, a further hyperlink may be used to look up case progress or to access the online Disclosure Log.

Authentication

Any links exposed for customers to use in a self-service scenario, e.g. when embedded in a web site, can be secured by requiring customers to log in to ManageMyRequests on first clicking the link. The log in requirement is optional and can be de-activated by appending the parameter "Login=false" to the hyperlink url. Login cannot be de-activated for the link to lookup case progress.

Alternatively, any links invoked from CRM or other customer systems can also be authenticated through a valid API access key. To allocate an access key, select the API Keys menu option from the Administration menu and follow the on-screen instructions. Each of the services then requires that two parameters, Key and Signature are included with the url. The Key parameter should contain a valid API key to identify the user/system making the call. The Signature parameter is made up of an MD5 hash of that user's secret key and either the Customer.Id parameter (when launching a form) or the CaseId parameter (when looking up case details) in the URL appended together. For example, if a user is issued with the following keys:

API key: 0c54a5a5855483e04c26de1dc
Secret key: 1e4ecd8c836bbd7bc9ae4b5e6

Then when invoking a URL to launch a form, this user should include theparameter Key=0c54a5a5855483e04c26de1dcto identify themselves. To calculate their signature value they would append together the value of the Customer.Id parameter (11091 in this example) and their secret key in the order Customer.Id + secret key, i.e. 110911e4ecd8c836bbd7bc9ae4b5e6 and that string should then be hashed using MD5 encoding. So the value of the Signature parameter passed to the web service would be:
Signature=2c54df4a72be46f711111f45c1935237

Network address restrictions

To enforce further security restrictions for any URL links secured through an API key, it is possible to limit the use of each allocated key pair to requests made from certain specified IP addresses. When allocating a new key pair, a list of allowed IP addresses can be set so that the given key and secret key can only be used to validate requests made from one of those IPs. Requests made from any other address using that key pair will be denied. Key pairs without IP restrictions will be accepted on requests made from any IP address.

Launch a form

To launch a ManageMyRequests form in order to create a new case, a web-page can link directly to the following url:

There are three predefined types that can be used to create cases through this interface:

InformationRequest

SubjectAccess

DisclosureRequest

A link using this most basic form of the URL will show the form as if it had been launched from ManageMyRequests with no customer record pre-selected, all the detail fields on the form will be empty and will need to be filled in by hand. However, if a customer has already been identified by the system creating the link to ManageMyRequests, those customers details can be passed directly into the form using further URL parameters. The following table lists all available parameters. Note that when a Customer.Id parameter is passed, any existing customer details on ManageMyRequests will be updated following submission of the form.

Also be aware that Customer details passed will be used to pre-populate the Representative page of the form if there is one, if not, they will be used to pre-populate the Customer page on the form.

Parameters

Name	Value
Customer.Id	The customer's unique reference
Customer.Title	The customer's title (Mr, Mrs, Ms etc)
Customer.FirstName	The customer's first name
Customer.Surname	The customer's surname
Customer.Organisation	The organisation this customer belongs to, if any
Customer.Address	The street component of the customer's address
Customer.Town	The town component of the address
Customer.County	The county, province or region component of the address
Customer.Country	The country component of the address
Customer.Postcode	The zip or postcode component of the address
Customer.Email	The customer's email address
Customer.Phone	The customer's landline phone number
Customer.Mobile	The customer's mobile phone number
Customer.ContactMethod	How the customer would prefer to be contacted (e.g. Email, Phone, Letter)
Customer.ContactConsent	Whether the customer agrees to be contacted again in future
Customer.Category	A category or type assigned to the customer
RequestDate	The date of the request if this had already been captured by the calling system. Values should be provided using the standard date format for your system, i.e. either dd/mm/yyyy or mm/dd/yyyy
RequestMethod	How the request was received, e.g. Email, Phone, Post, if this had already been captured by the calling system
ExternalId	An existing reference for the case. If passed, this will be stored and made available to search against.
Team	The code of the team to assign this case to. If no code is passed, the case will be assigned to the generic 'Unallocated Casework' team where it can be re-assigned further.
Login	Passing false will enable completion of the form without logging in. The default value for this parameter is true.
Title	A title to display for the form. Pass 'none' to suppress display of a title.
Style	A reference to a style code to invoke the form through a custom style template, as defined under Self Service Style Templates in the Administration menu.
Redirect	A URL to redirect to after completion of the form or during completion of the form.
AutoRedirect	Set this to true to redirect automatically after form completion
RedirectLabel	A label to display for the redirect hyperlink. The label will default to 'Go back'.

View case progress

Once a case has been created in the system, the current status of the case can be displayed together with a summary of actions taken so far. To launch this page, use the following URL, passing in the reference of the case. The reference passed in can contain either our reference or your own reference, if this had been associated with the case.

Parameters

Name	Value
Title	A title to display. Pass 'none' to suppress display of a title.
Style	A reference to a style code to invoke details through a custom style template, as defined under Self Service Style Templates in the Administration menu.
Redirect	A URL for use in a redirect link displayed, e.g. to go back to the originating page.
RedirectLabel	A label to display for the redirect hyperlink. The label will default to 'Go back'.

View the Disclosure Log

Use this link to publish a searchable register of FOI decisions to your website.

Parameters

Name	Value
Title	A title to display. Pass 'none' to suppress display of a title.
Style	A reference to a style code to invoke details through a custom style template, as defined under Self Service Style Templates in the Administration menu.