External Search Development

External search allows third party applications to open IFS Enterprise Explorer forms and search for a specific object. This page contains a description of the functionality along with a guide for writing programs to generate External Search URL's.

Contents

Background

Sometimes there is a need to query an IFS Enterprise Explorer (IFS EE) form outside the application. The external_search URL extension for the ifsapf and ifswin protocols allows such a use case. It provides a set of rules for creating simple queries into IFS EE from outside the application.

Some Examples

From inside the IFS EE if you want to do a search by copying and pasting something into the address bar you do it like this:

ifsapf:frmDocumentContainer?COMPANY=10&external_search=doc_class%3d100

The key part here is the external_search bit. Notice that it's URL encoded. %3d here is the '=' character. The un-encoded form of the external search string will look like this:

doc_class=100

You can use multiple declarations together like so:

doc_class=100&doc_no=12345

You need to escape literal uses of '&' and '=' with a '\' for the parser to recognize them:

doc_class=Jack\&Jill&doc_no=12345

Spaces within the data is allowed:

doc_class=My Doc Class&doc_no=12345

Wildcards are not allowed. This is a limitation with the way the resulting SQL gets parsed by Oracle. The resultant statement does an equivalence comparison and does not use the  "LIKE" keyword, which causes wildcards to be ignored. I.e. think of the above as:

WHERE doc_Class = 'jack' …

And not

WHERE doc_class LIKE 'jack' …

When calling from outside the application, the entire ifsapf URL is passed into the activation URL (the one ending with the Ifs.Fnd.Explorer.Application) like so:

http://someserver:8080/somepath/Ifs.Fnd.Explorer.application?url=ifsapf%3afrmDocumentContainer%3fCOMPANY%3d10%26external_search%3ddoc_class%253d100

Notice the ifsapf bit is URL encoded. It's important to note here that the external_search content is being encoded twice. Once for the external_search bit when creating the URL, and once when the whole ifsapf URL is encoded.

The syntax for an external_search is identical in an ifswin URL. Here's an example for the ListPersons feature in the Solution Manager, where a search is being done for the "Name" field. 

ifswin:Ifs.Application.UserAdministration.ListPersons?external_search=NAME%3dDemo%20User%20Deutschland

Formal Definition

Rules

external_search = 'external_search=' expression_list

expression_list = equivalance_expression
                | equivalance_expression '&' expression_list

equivalance_expression = TOK_NAME '=' TOK_VALUE

Tokens

TOK_NAME: An alphanumeric string. Can contain "_" characters. Eg: "Customer_ID" or "Doc_Class",

TOK_VALUE: An alphanumeric string. Can contain "&" and "=" characters but they need to be escaped (with "\&" and "\=").

An example external_search string's expression_list before encoding:

doc_class=100&doc_no=ERTT&doc_sheet=1&doc_rev=A1

 

Writing an External Search String Generator

This can be done easily. You need to know the following in advance:

  1. The form you wish to open
  2. The field names on the database side that you wish to search on.
  3. The format of the external search string (above).

Generating the string can be done by writing a program in a language of your choice to do the following:

  1. Create the external_search parameter string by stringing together a set of fields as name value pairs.
    doc_class=100&doc_no=ERTT&doc_sheet=1&doc_rev=A1
  2. Encode the external_search parameter string and create the external_search string.
    external_search=doc_class%3d100%26doc_no%3dERTT%26doc_sheet%3d1%26doc_rev%3dA1
  3. Attach the external search string to an ifsapf URL or an ifswin URL.
    ifsapf:frmDocumentContainer?COMPANY=10&external_search=doc_class%3d100%26doc_no%3dERTT%26doc_sheet%3d1%26doc_rev%3dA1
  4. Encode the whole ifsapf or ifswin URL.
    ifsapf%3afrmDocumentContainer%3fCOMPANY%3d10%26external_search%3ddoc_class%253d100%2526doc_no%253dERTT%2526doc_sheet%253d1%2526doc_rev%253dA1
  5. Finally attach the generated URL to the activation URL for the IFS EE instance that is being targeted.
    http://someserver:8080/somepath/Ifs.Fnd.Explorer.application?url=ifsapf%3afrmDocumentContainer%3fCOMPANY%3d10%26external_search%3ddoc_class%253d100%2526doc_no%253dERTT%2526doc_sheet%253d1%2526doc_rev%253dA1

Now navigating to the URL in step [5] will cause IFS Enterprise Explorer to open the correct form and populate it with records based on the search criteria in the external_search string.