AR System APIs Quick Start - Jython

Version 1
    Share This:

    << AR System APIs and Intergration Interfaces Overview

     

    Comparison to other languages >> C Java Driver Perl C# VB

     

    Description

     

    NOTE

     

    IMPORTANT: This API continues to remain officially unsupported at this time.   If customers seek to use a supported AR System API, the C/Java API remains  the APIs of choice for our customer's various development needs.

     

    Less IMPORTANT: Document was created with the following versions referenced:

    • AR System 7.6.04 sp2
    • Eclipse 3.7.2
    • PyDev 2.5
    • Jython 2.5.3b1

     

    While other versions of the above may just work, I cannot guarantee that that they will work the same (but chances are they will).  For those who wish to have a different setup (e.g. PyCharm, Emacs, etc), additional / different setup steps may be required.

     

    The Jython API directly imports the full featured AR System Java API giving programmers the ability to code AR System programs using a powerfull dynamic language that allows for faster prototyping then a typical Java or C API allows.

     

    In essence it is equivalent to AR System Java API however is syntatically Python.  Because of the close tie to the Java API, the provided JavaDocs for the AR System Java API is the only API documentation you will require outside of a general working knowledge of Jython &| Python.

     

    Precursor

     

    All programs below are full programs that can be copy & pasted into an appropriete configured Jython IDE and will run upon setting the correct global variables for:

    • SERVER
    • USERNAME
    • PASSWORD
    • TCPPORT

     

    A correctly configured Jython IDE could be the latest versions of Eclipse, PyDev & Jython.  The only real requirement is to include the desired AR System Java API Jar files into your project which include at a minimum the following (I typically include them in my project directory to avoid classpath issues):

     

    • arapi7604_build002.jar
    • log4j-1.2.14.jar

     

    The above files typically can be found in your AR System installation directory in the \ARSystem\Arserver\api\lib folder.

    Sample Create

    The following snippet will overview the creation of a context to the target AR System, login and then create an entry in the "User" form.

     

    from com.bmc.arsys.api import ARServerUser, ARException, Entry, Value

     

    SERVER = '<AR SERVER NAME>'

    USERNAME = '<USERNAME>'

    PASSWORD = '<PASSWORD>'

    TCPPORT = '<PORT>'

     

    def create_entry():

        """This is how to create an entry in the User form with minimal information

        """

        try:

            schema = 'User'  # We define our form here

            entry = Entry()  # We create an Entry object

            entry.put(7, Value('0'))  # Set Status

            entry.put(101, Value('TestUserCG01'))  # Set Login ID

            entry.put(8, Value('New UserCG01'))  # Set Full Name

            entry.put(103, Value('MyCG@Example.org'))  # Set Email Address

            entry.put(109, Value('1'))  # Set License Type

            entry.put(110, Value('0'))  # Set Full Text License Type

            result = ars.createEntry(schema, entry)  # Create the entry

            print('Entry %s created' % result)

        except ARException, e:

            print(e)

     

    def main():

        global ars

        try:

            ars = ARServerUser(USERNAME, PASSWORD, '', SERVER)

            ars.setPort(TCPPORT)

            ars.login()

            create_entry()

            ars.logout()

        except ARException, e:

            print(e)

     

    if __name__ == '__main__':

        main()


    Sample Search

    The following snippets will cover various search scenarios that can be useful, all functions included in main so running this full program will run all the scenarios.  For full value, create some users with @example.org as their email address or change the qualification to match specific email address for your organization.

     

    from com.bmc.arsys.api import ARServerUser, ARException, Entry, Value

     

    SERVER = '<AR SERVER NAME>'

    USERNAME = '<USERNAME>'

    PASSWORD = '<PASSWORD>'

    TCPPORT = '<PORT>'

     

    def get_entry():

        """This is how to return a single entry using the getEntry method

        """

        try:

            schema = 'User'  # We define our form here

            entry_id = '000000000000001'  # We define our target entry_id here

     

            # How to return an entry with all fields

            entry = ars.getEntry(schema, entry_id, None)

            print(entry)

     

            # How to return an entry with certain fields (Field ID 1,2,3,4,5 in this scenario)

            entry = ars.getEntry(schema, entry_id, [1, 2, 3, 4, 5])

            print(entry)

     

            # How to loop through and print entry, accounting for null values w/ toString method

            entry = ars.getEntry(schema, entry_id, None)

            for i in entry:

                print '%s: %s' % (i, entry[i].toString())

        except ARException, e:

            print(e)

     

    def get_multiple_entries():

        """This is how to return multiple entries without any qualification using the getListEntry method

        """

        try:

            schema = 'User'  # We define our form here

            entries = ars.getListEntry(schema, None, 1, 0, None, None, False, None)

            print(entries)

        except ARException, e:

            print(e)

     

    def get_multiple_entries_qual():

        """This is how to loop through a returned list of entries and then use that

        list to getEntry the values, the key is to use getEntryID() to pull out the

        entry_id of the records so that it can be used to iterate and used with the

        getEntry method.

     

     

        Parameters:

        String formName, QualifierInfo qualification, int firstRetrieve,

        int maxRetrieve, List<SortInfo> sortList, List<EntryListFieldInfo>

        entryListFields, boolean useLocale, OutputInteger nMatches)

     

     

        To build a QualifierInfo object, use the parseQualification method if you

        plan on using FieldID or DBNames, if you want to use labels, then you need

        to add a 3rd parameter (between form and qual) that is "" for use labels

        from default view or "SomeViewName" if you want labels from a specific view

        from the form provided

        """

        try:

            schema = 'User'  # We define our form here

            query = "'Email Address' LIKE \"%@Example.org\""  # We define our qualification

            qual = ars.parseQualification(schema, query)  # We parse and encode the qualification into internal representation

            entries = ars.getListEntry(schema, qual, 0, 0, None, None, False, None)  # We query our form with our qualfication

     

            #For each entry that matched our qualification, loop through and call getEntry to return all fields

            for entry in entries:

                result = ars.getEntry(schema, entry.getEntryID(), None)

                for fields in result:

                    print('%s: %s' % (fields, result[fields].toString()))

        except ARException, e:

            print(e)

     

    def main():

        global ars

        try:

            ars = ARServerUser(USERNAME, PASSWORD, '', SERVER)

            ars.setPort(TCPPORT)

            ars.login()

            get_entry()

            get_multiple_entries()

             get_multiple_entries_qual()

            ars.logout()

        except ARException, e:

            print(e)

     

    if __name__ == '__main__':

        main()


    Sample Modify

    The following snippets will cover how to modify existing requests.

     

    from com.bmc.arsys.api import ARServerUser, ARException, Entry, Value

     

    SERVER = '<AR SERVER NAME>'

    USERNAME = '<USERNAME>'

    PASSWORD = '<PASSWORD>'

    TCPPORT = '<PORT>'

     

    def modify_entry():

        """This is how to modify an entry, you need to create an instance of an

        Entry class and put the values you want to change only, values you don't

        specify won't be touched.

     

        Parameters: schema, entry_id, Entry, time stamp (used for comparison so

        that the server can check to make sure the last time you looked at the

        record it hasn't been updated, just pass None to bypass this check),

        nOption (this is 0 if you want to be able to update fields referenced in

        Joins or 1 if you don't want to be able to stop from updating fields

        in joins

        """

        try:

            schema = 'User'  # We define our form here

            entry_id = '000000000001083'  # We define the entry to modify here

            entry = Entry()

            entry.put(103, Value('MyCG_updated@Example.org'))  # 103: Email Address

            ars.setEntry(schema, entry_id, entry, None, 0)  # Modify the entry

            print('Successfully modified entry')

        except ARException, e:

            print(e)

     

    def main():

        global ars

        try:

            ars = ARServerUser(USERNAME, PASSWORD, '', SERVER)

            ars.setPort(TCPPORT)

            ars.login()

            modify_entry()

             ars.logout()

        except ARException, e:

            print(e)

     

    if __name__ == '__main__':

        main()

     

    Exception Handling

    Because Jython leverages the AR System Java API, the native API exceptions will be thrown and can be caught using a try/except block statement as shown in the various examples above.  Most methods will throw ARException  and it is best practice to contain most of your program which does calls to the AR System within a try block to catch the exceptions the AR System may throw.

     

    Compilation

    While the power of Jython & Python is it's dynamic nature, sometimes it is not always possible to have a fully configured IDE or Jython environment where needed which can be challenging.  In order to work around this, the beautiful Apache Maven (http://maven.apache.org) tool can be utilized to pack a Jar file that can be run directly within a JVM which will exist on all Remedy servers since a JVM is a requirement of the solution.  The Jar file will unfortunatly be quite big (15-20MB in size) however will be 100% self contained.

     

    The Jar will contain:

    • Jython
    • AR System Java API Jar
    • Apache log4j Jar
    • <any additional libraries/modules required>
    • Your program code
    • Java boilerplate code for interacting with Jython runtime

     

    For a instructions on setting up an Apache Maven project to run Jython code, please see: http://mavenjython.sourceforge.net/compile/ and the related Example project: http://mavenjython.sourceforge.net/compile/demo/

     

    More details and related links

    For more information on Jython: http://www.jython.org/