Skip to main content
Kinetic Community

Crib Sheet

A quick crib sheet of Klink's framework calls and their parameters.


Specifying a User


The easiest way to specify a user is to do so via the Url (in the format "<User>:<Password>@" prepended to the server information, however you can also specify the user and password through HTTP basic authentication (and in fact if no user and pass information is included the Klink server will return an HTTP 401 Unauthorized exception, which will force most browsers to prompt for a user and pass).


Conventions

Everything between '<' and '>' signifies values that should be replaced as appropriate.
Everything between '[' and ']' signifies options values that can be replaced as appropriate.
Everything between '"' and '"' signifies literal values.

For Brevity the following format is abbreviated as <Datasource>:[<User>[:<Password>]@]<Server>[:<TcpPort>[:<RpcPort]]

Klink Framework Calls


ABOUT - /klink/about

This call returns information about the running system. This includes the version information for both Klink and the libraries requried for klink to run. Libraries shown as missing will prevent Klink from functioning properly.

LOGCONFIG - /klink/logconfig

Http Parameters

  - ?configfile="DEFAULT"|[fileName]
  - ?configproperties=<name>:<value>[;<name>:<value>]
This framework call is disabled by default. This framework call can be enabled by uncommenting it from the struts-config.xml file. For more information please see the Installation and Configuration Guide. When logconfig is called without specifying a parameter the current log4j configuration parameters are displayed, along with the current source of those configurations. Specifying a configfile will do a live reload (flushing current properties and loading the new) of the logging configuration, loading parameters from the file specified. Properties can be added/modified by hand via the configproperties parameter. Using the configproperties parameter will not force a flush of the current configuration.

Sample: http://<klinkhost>/klink/logconfig
  This will display the current log4j configuration parameters.
Sample: http://<klinkhost>/klink/logconfig?configfile="DEFAULT"
  This will reset the log4j configuration parameters based on the file specified in the   application's web.xml file (See the Installation and Configuration Guide for more   information).
Sample: http://<klinkhost>/klink/logconfig?configfile=C:\commons\log4j\GenericDEBUGLogging.cfg
  This will flush the current log4j configuration parameters and load a new configuration   based on the file specified (In this case GenericDEBUGLogging.cfg).
Sample: http://<klinkhost>/klink/logconfig?configproperties=log4j.logger.com.kd.klink:DEBUG, fileAppender
  This will either add or modify the current log4j.logger.com.kd.klink configuration   parameter without flushing previous configurations.
Sample: http://<klinkhost>/klink/logconfig?configfile=C:\commons\log4j\GenericDEBUGLogging.cfg&configproperties=log4j.logger.com.kd.klink:DEBUG, fileAppender
  This will flush the current configurations, load the configurations from the configfile   specified, and add or modify the current log4j.logger.com.kd.klink configuration parameter.

Meta Framework Calls

CONFIGURATIONS - /klink/configurations/<Datasource>

Http Parameters

  - ?items=<ConfigurationItem>[,<ConfigurationItem>[...]]
Retrieves configuration information for the Remedy server specified by Datasource. Configuration items are specified by name, a complete list is available by making a configurations call without including the items parameter.

Sample1: http://<klinkhost>/klink/configurations/<datasource>
  This will return a list of all of the configurations for the <datasource> Remedy Server.
Sample2: http://<klinkhost>/klink/configurations/<datasource>?items=SERVER_NAME,SERVER_VERSION
  This will return only the configurations specified in the items parameter.

PERMISSIONS - /klink/permissions/<Datasource>/<Structure>[/<ItemID>[,<ItemID>[...]]]


Http Parameters
  - ?items="all"|<StructureItemID>[,<StructureItemID>[...]]
Retrieves form and field permissions. The base framework call will return permissions to the form itself. When the items parameter is included the framework call will return form permissions and the permissions for all of the specified StructureItemIDs. When StructureItemIDs are specified as a part of the framework call only those specified will be returned, without the form permission information.

Sample1: http://<klinkhost>/klink/permissions/<datasource>/<structure>
  This will return the permissions for the structure specified.
Sample2: http://<klinkhost>/klink/permissions/<datasource>/<structure>?items=1,2,3
  This will return the permissions for the structure speciried and the three fields shown.
Sample3: http://<klinkhost>/klink/permissions/<datasource>/<structure>?items=all
  This will return the permissions for the structure specified and the permissions for all   of the structure items associated with that structure.
Sample4: http://<klinkhost>/klink/permissions/<datasource>/<structure>/1
  This will return the permissions for structure item 1 on the structure specified.
Sample5: http://<klinkhost>/klink/permissions/<datasource>/<structure>/1,2,3
  This will return the permissions for structure items 1, 2, and 2 on the structure specified.

STATISTICS - /klink/statistics/<Datasource>

Http Parameters
  - ?items=<StatisticsItem>[,<StatisticsItem>[...]]
Retrieves statistics information for the Remedy server specified by Datasource. Statistics items are specified by name, a complete list is available by making a statistics call without including the items parameter.

Sample1: http://<klinkhost>/klink/statistics/<datasource>
  This will return a list of all of the statistics for the <datasource> Remedy Server.
Sample2: http://<klinkhost>/klink/statistics/<datasource>?items=CURRENT_USERS
  This will return only the statistics specified in the items parameter.

USERCHECK - /klink/usercheck/<Datasource>


Validates the user by attempting to log in to the Remedy system. If the user was unable to log in (due to bad password, bad account name on a server with guest accounts disabled) or there were any messages that occured during login (such as warning messages if the user has been logged in as a guest) then these will be included in the Klink response. The result element contains the user credentials used for the login. The below examples are all specifying the user credentials as part of the datasource in the framework call, however usercheck functions the same when they are specified as the HTTP Basic Authentication header.

Sample1: http://<klinkhost>/klink/user/TestUser:guestpass@<datasource>
  This will return the context info and no messages because everything is correct.
Sample2: http://<klinkhost>/klink/user/TestUser:wrongpass@<datasource>
  This will return an Error message because the password is incorrect.
Sample3: http://<klinkhost>/klink/user/NoUser@<datasource>
  Assuming NoUser is a not an existing user, this will return the context info and a   warning message if guest accounts are enabled or an error message.

Structure Framework Calls

STRUCTURE - /klink/structure/<Datasource>/<Structure>

Http Parameters
  - ?items="all"|<StructureItemID>[,<StructureItemID>[...]]
Returns a description of the structure specified. By default, this will describe all data-related structure items. To include non-data-related structure items set the items parameter to "all". A subset of structure items can be retrieved by specifying a list of IDs as the value of the items parameter.

Sample1: http://<klinkhost>/klink/structure/<datasource>/<structure>
  This returns a description of the data-related structure items on the structure specified.
Sample2: http://<klinkhost>/klink/structure/<datasource>/<structure>?items=all
  This returns a description of all of the structure items on the structure specified.
Sample3: http://<klinkhost>/klink/structure/<datasource>/<structure>?items=1,3,7
  This returns a description of the structure items with IDs 1, 3, and 7.

STRUCTURES - /klink/structures/<Datasource>

Retrieves a list of all of the structures the requesting user has access to on the Remedy Server.

Sample1: http://<klinkhost>/klink/structures/<datasource>

Data Framework Calls

ATTACHMENT - /klink/attachment/<Datasource>/<Structure>/<EntryID>/<AttachmentItemID>

This returns an attachment entry item and is the only way to retrieve the actually attachment data. Calls to entry will only return the attachment name and size. The data is represented as the file contents base64 encoded. To retrieve the byte stream of the attachment simply decode the value of the data element.

CREATE - /klink/create/<Datasource>[/<Structure>]


Http Parameters
  - ?entry=<EntryXml>
  - ?items=<StructureItemID>[,<StructureItemID>[...]]
  - ?returnentry="true"|"false"
This will create an entry within the specified structure. The simplest way to specify the entry information is on the Url via the http parameter "entry". However, the best practice for production systems is to set the content type of the HTTP request to be application/xml and include the entry xml as the request body. The format of the entry xml is identical to the xml returned as a result of the "entry" framework call, however only the entry items required for creation need to be present. By default, this call will only return an empty Entry element with the ID and Structure attributes set. If a full view of the EntryItems is required, the "returnentry" parameter can be set to true. The Structure can either be set as an attribute to the Entry element or as part of the request Url. If it appears in both and is different, Klink will return a ModelException.

Sample1: http://<klinkhost>/klink/create/<datasource>?entry=<Entry Structure="TestForm"/>
  This will return likely return an error because field 2 (Submitter) and 8 (Short Description) are required and don't have defaults.
Sample2: http://<klinkhost>/klink/create/<datasource>/TestForm?entry=<Entry Structure="TestForm"><EntryItem ID="2">Bob</EntryItem><EntryItem ID="7">Assigned</EntryItem><EntryItem ID="8">Description</EntryItem></Entry>
  This will create an entry in the Assigned state (field id 7 is Status).
Sample3: http://<klinkhost>/klink/create/<datasource>/TestForm?returnentry=true&entry=<Entry><EntryItem ID="2">$USER$</EntryItem><EntryItem ID="7">Assigned</EntryItem><EntryItem ID="8">Description</EntryItem></Entry>
  This will create an entry in the Assigned state and return the full description of the entry.
Sample4: http://<klinkhost>/klink/create/<datasource>/TestForm?returnentry=true&entry=<Entry Structure="TestForm2"><EntryItem ID="2">$USER$</EntryItem><EntryItem ID="7">Assigned</EntryItem><EntryItem ID="8">Description</EntryItem></Entry>
  This will return and error since the implicit and explicit structures are different.

DELETE - /klink/delete/<Datasource>/<Structure>/<EntryID>


Removes an entry from the database.

Sample1: http://<klinkhost>/klink/delete/<datasource>/<structure>/000000000000001
  This will physically remove the entry with ID 000000000000001 from the structure specified.

ENTRIES - /klink/entries/<Datasource>/<Structure>


Http Parameters
  - ?items="all"|<EntryItemID>[,<EntryItemID>[...]]
  - ?limit=<Limit>
  - ?qualification=<QualificationString>
  - ?range=<First>-<Last>
  - ?sort=<EntryItemID>["+"|"-"][,<EntryItemID>["+"|"-"][...]]
  - ?target=["min"|"max"|"rand"|"all"]
This returns a list of entries matching specific criteria. The call retrieves a list of up to the limit specified entries (and any entry items included in the items parameter, or all of them if "all" is specified) matching the qualification, sorts them according to the sort parameter (the entry item id by default), applies the range to this sorted list, then selects a target from that range. The items parameter affects what information about the entry is returned, by default only the entry id. The limit parameter sets the maximum number of entries to retrieve, however the limit can't be larger then that supported by the datasource. The limit defaults to the datasources set limit, or unlimited if the datasource doesn't have a limit. The qualification can be any qualification or query string, which the datasource supports, and defaults to a qualification, which is always true. The range parameter accepts a list of ranges, which can be either single indexes or a range in the format <first>-<last> and defaults to the entire list of entries. The sort parameter takes a list of entry item IDs to sort on and can either use increasing sorting (+) or decreasing sorting (-). By default, entries are sorted by ID. Finally, the target parameter defines which of the entries within the range are to be returned; the first, the last, a random entry, or all of the entries by default.

Sample1: http://<klinkhost>/klink/entries/<datasource>/TestForm
  This will return the IDs of all of the entries in the TestForm structure.
Sample2: http://<klinkhost>/klink/entries/<datasource>/BensForm?items=7,8&qualification='1'>9&range=1,3-5&sort=1-,7&target=rand
  This will retrieve a list of entries with entry item 1 (or Field 1 for Remedy, Request ID by default) greater than nine, sort them based on decreasing values of entry item 1 and increasing values of entry item 7 (Field 7, or status, for Remedy), pick a random entry from the first, third, fourth, or fifth entries, and return the Entry ID, Status (field 7), and Short Description (field 8).

ENTRY - /klink/entry/<Datasource>/<Form>/<EntryID>[,<EntryID>[...]]

HttpParameters
  - ?items="all"|<EntryItemID>[,<EntryItemID>[...]]
This will return the generic xml representation for each of the specified entry IDs. By default, only the entry items that have non-null values will be returned. Null valued entry items can be included by setting the Http parameter items to "all". Additionally, a subset of specific entry items can be requested by passing in a list of entry item IDs through the items parameter.

Sample1: http://<klinkhost>/klink/entry/<datasource>/<structure>/000000000000001
  This will return an Xml description of the entry with the ID specified from the structure specified (but won't include entry items with null values).
Sample2: http://<klinkhost>/klink/entry/<datasource>/<structure>/000000000000001?items=all
  This will return an Xml description of the entry with the ID specified from the structure specified including all null valued entry items.
Sample3: http://<klinkhost>/klink/entry/<datasource>/TestForm/000000000000008,000000000000012
  This will return an Xml description of the entries specified from TestForm (but won't include fields with null values).
Sample4: http://<klinkhost>/klink/entry/<datasource/TestForm/000000000000008,000000000000012?items=8
  This will return an Xml description of the entries specified from TestForm but will only include the entry item with an ID of 8 (short description).

UPDATE - /klink/update/<Datasource>/<Structure>[/<EntryID>]

  - ?entry=<EntryXml>
  - ?items=<StructureItemID>[,<StructureItemID>[...]]
  - ?returnentry="true"|"false"
This will update an entry within the specified structure. As with create, the entry xml can be specified either by the http parameter "entry" or as an application/xml Http request body and is the same format as that which is returned by the entry framework call. By default, this call will only return an empty Entry element with the ID and Structure attributes set. If a full view of the EntryItems is required, the "returnentry" parameter can be set to true. The Structure can either be set as an attribute to the Entry element or as part of the request Url. If it appears in both and is different, Klink will return a ModelException. Similarly, the entry ID can either be set as an attribute to the Entry element or as part of the request Url. If the entry ID is not present in either, or it appears in both and is different, a ModelException will be thrown.