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. |