Changes between Initial Version and Version 1 of ARInsideDocumentation311

09/01/14 08:36:36 (3 years ago)



  • ARInsideDocumentation311

    v1 v1  
     4<h1 style="color: #039;"> 
     5 ARInside Documentation 
     8Version: 3.1.1 ([ Release Notes]|[wiki:ARInsideWhatsNew310 What's New 3.1.0]) 
     11== Introduction == 
     12ARInside is a command-line application that generates linked HTML pages to document ARSystem workflow. The program can be run in online mode connecting to an ARSystem server or in file mode using an XML server definition export file. In advance a Packing List with all ARSystem server objects to exclude from documentation can be specified in the application configuration. 
     14ARInside was initially designed by Stefan Nerlich, who has made the source code public in mid 2009. From this day on ARInside is maintained by a few developers and released under the "General Public License Version 2" (GPLv2). 
     16== Getting Started == 
     17We start here with a simple example that documents all workflow of a local installed AR-system server. The example assumes ARInside is located in {{{C:\arinside}}}. Additionally an administrative user named "Demo" with password "pass" is required on your server.  So first start a new command shell and go to the installation folder of ARInside. The prompt should look like this: 
     21Now enter the following command to start documentation of your server. 
     23C:\arinside> arinside –i settings.ini –l Demo –p pass –s localhost 
     25After that ARInside connects to your server and starts documenting all forms, fields and workflow. 
     26What’s the meaning of those arguments? Ok, here is a short explanation: The "-i" argument specifies the configuration file. ARInside comes with a default configuration file named "settings.ini" which we use in this example.  The "-l" switch defines the login name and "-p" the password ARInside will use to connect to the server specified by the "-s" switch. 
     27Depending on the size of your application it can take several hours to finish. Please be patient. If its finished, you’ll find the generated documentation under {{{C:\arinside\DefaultOutputFolder}}}. Open the contained index.htm file with a web-browser you like. 
     29== Requirements == 
     30On the Microsoft Windows™ platform the following software-components must be installed 
     31- Visual C++ 2008 Redistributable Package SP1 
     32Make sure the following points are fulfilled: 
     33- The specified username should have administrator rights. Otherwise the documentation will be incomplete. 
     34- ARInside supports AR-server version 7.1 and higher. It might also work with older versions. However testing focuses mainly on the specified versions. 
     36== Command Line Arguments == 
     37The following table describes all the available command line options. 
     38|| '''Argument''' || '''Type''' || '''Description''' || 
     39|| -i <string> || required || File Name of the configuration file || 
     40|| -s <string> || optional || ARSystem server name to connect || 
     41|| -l <string> || optional || Login Name used to connect to the ARSystem server || 
     42|| -p <string> || optional || Password || 
     43|| {{{-t <integer>}}} || optional || The port number that the program will use to communicate with the AR System\\server. If you do not specify this parameter or provide 0 for the port number, your\\program will use the port number supplied by the portmapper. This parameter is\\overridden by the ARTCPPORT environment variable. || 
     44|| {{{-r <integer>}}} || optional || The RPC program number of the server. Specify 390600 to use the admin server, a\\number from 390621 to 390634 or 390636 to 390669 or 390680-390694 to use a\\private server, or 0 (default) to use the fast or list server queue. This parameter is\\overridden by the ARRPC environment variable. || 
     45|| -o <string> || optional || The output directory of the documentation. || 
     46|| --slow || optional || Disables fast object loading || 
     47|| -v || optional || If specified it enables verbose program output. || 
     48|| -h || optional || Shows more detailed command line usage information. || 
     50=== Examples === 
     52arinside.exe -s servername -l Demo -i settings.ini 
     54arinside.exe -l Demo -s servername -p mypassword -i settings.ini 
     56arinside.exe -p "my&password" -i settings.ini -s servername -l Demo 
     58arinside.exe -s servername -l Demo -i "my settings.ini" 
     60arinside.exe -s servername -l Demo -i "my settings.ini" -t 1044 -r 390621 
     62=== Notes === 
     63- The order of the parameters is irrelevant 
     64- Parameters with special characters (for example empty spaces) can be surrounded by quotation marks 
     66== Configuration File == 
     67The ARInside application settings can be configured using a simple text-file. ARInside comes with a [ sample configuration file] you should change as needed. The settings are grouped into four categories described below. 
     69Starting with ARInside 3.0.1 you could save the connection information within the ini file. Some settings could be set on the command line too. If you do this, the command-line arguments take precedence over the ini-file settings. 
     71|| '''Option''' || '''Type''' || '''Default value''' || '''Description''' || 
     72|||||||| '''Server Settings''' || 
     73|| !ServerName || String || <EMPTY> || The server name ARInside should connect to. || 
     74|| Username || String || <EMPTY> || Login name used to connect to the ARSystem server. || 
     75|| Password || String || <EMPTY> || Password used to connect to the ARSystem server. || 
     76|| TCPPort || Integer || 0 || The port number that the program will use to communicate\\with the AR System server. If you do not specify this setting\\or provide 0 for the port number, your program will use the port\\number supplied by the portmapper. This setting is overridden\\by the ARTCPPORT environment variable. || 
     77|| RPCPort || Integer || 0 || The RPC program number of the server. Specify 390600 to use\\the admin server, a number from 390621 to 390634 or 390636\\to 390669 or 390680-390694 to use a private server, or 0\\(default) to use the fast or list server queue. This setting is\\overridden by the ARRPC environment variable. || 
     78|| APITimeout || Integer || 0 || If you have a big amount of workflow on your server, it's\\possible that ARInside fails to load objects like e.g. Active Links.\\In this case you should increase the api-timeout. || 
     79|||||||| '''Application Settings''' || 
     80|| !TargetFolder || String || <EMPTY> || Relative or absolute path to the output directory where the\\documentation is saved. This setting could be overridden by\\the {{{-o}}} command line argument. || 
     81|| !FileMode || Boolean || FALSE || Specify if the application will connect to an ARSystem server\\(!FileMode=FALSE) or load information from a file specified by\\ObjListXML setting (!FileMode=TRUE). || 
     82|| ObjListXML || String || <EMPTY> || An ARSystem Administrator server definition file in XML\\format. The parameter specifies the filename and is only used\\when !FileMode is set to TRUE. Refer to the ARSystem\\Administrator Guide how to export server definitions in XML\\format. || 
     83|| UTF-8 || Boolean || FALSE || Refer to your ARSystem Database configuration if UTF-8\\encoding is required. || 
     84|| !BlackList || String || <EMPTY> || Name of an ARSystem !PackingList with a list of ARSystem\\objects which should be excluded from the documentation.\\Refer to the ARSystem Administrator Guide about how to\\create a !PackingList and add/remove objects to the list. || 
     85|| !LoadServerInfoList || Boolean || TRUE || Load extended server informations.  || 
     86|| !CompactFolder || Boolean || FALSE || Use NTFS file system compression to save some disk space.\\The application uses the Windows NT™ compact command. || 
     87|| !DeleteExistingFiles || Boolean || FALSE || Delete all existing files in target folder. || 
     88|| !OldNaming || Boolean || FALSE || Since ARInside 3.0.1 the file- and folder-names in the output\\directory are generated using the object name, e.g. the schema\\name. On previous versions a consecutive number was used. If\\you set this parameter to TRUE, the old file naming convention\\will be used. This option exists for backward compatibility. || 
     89|| GZCompression || Boolean || FALSE || With version 3.0.2 ARInside supports gzip-compressed html\\files. In combination with an apache server you can access the\\compressed documentation. ARInside generates the needed\\.htaccess file as well. || 
     90|| !OverlayMode || Boolean || TRUE || If this option is set to TRUE and the servers version is 7.6.04\\and higher, ARInside will document additional details of the\\overlay-feature. || 
     91|||||||| '''Data Retrieval''' || 
     92|| !LoadUserList || Boolean || TRUE || Load User data from ARSystem form "User". Requires the\\following fields in the form:\\ \\!RequestId (1), !LoginName (101), Email (103), !GroupList (104),\\!FullName (8), !DefNotify (108), !LicType (109), !FtLicType (110),\\!CreatedBy (2), Created (3), !ModifiedBy (5), Modified (6)\\ \\If this parameter is set to „FALSE“ no user data will be loaded. || 
     93|| !UserForm || String || User || Name of the ARSystem user form. || 
     94|| !UserQuery || String || '1'!=$NULL$ || Query to restrict the number of users returned from the server. || 
     95|| !LoadGroupList || Boolean || TRUE || Load Group data from ARSystem form "Group". Requires the\\following fields in the form:\\ \\!RequestId (1), !GroupName (105), !GroupId (106), !GroupType\\(107), !LongGroupName (8), !CreatedBy (2), Created (3),\\!ModifiedBy (5), Modified (6), Category (120), Computed Group\\Definition (121)\\ \\If this parameter is set to “FALSE” no group data will be loaded. || 
     96|| !GroupForm || String || Group || Name of the ARSystem group form. || 
     97|| !GroupQuery || String || '1'!=$NULL$ || Query to restrict the number of groups returned from the\\server. || 
     98|| !LoadRoleList || Boolean || TRUE || Load Roles data from ARSystem form "Role". Requires the\\following fields in the form:\\ \\!RequestId (1), !ApplicationName (1700), !RoleName (1701),\\RoleID (1702), !GroupName Test (2001), !GroupName\\Production (2002), !CreatedBy (2), Created (3), !ModifiedBy (5),\\Modified (6)\\ \\If this parameter is set to “FALSE” no role data will be loaded. || 
     99|| !RoleForm || String || Roles || Name of the ARSystem role form. || 
     100|| !RoleQuery || String || '1'!=$NULL$ || Query to restrict the number of roles returned from the server. || 
     101|| !MaxRetrieve || Integer || 0 || The maximum number of entries to retrieve. Use this\\parameter to limit the amount of data returned if the\\qualification does not sufficiently narrow the list. Specify\\0 to assign no maximum. || 
     102|||||||| '''Layout''' || 
     103|| !CompanyName || String || yourcompanyname || Your company name displayed in the documentation. || 
     104|| !CompanyUrl || String || `` || Html link to the specified company (!CompanyName) || 
     105|| !RunNotes || String || <EMPTY> || Additional notes that will display on the main page. || 
     107=== Recommended Configuration === 
     108The ARInside package comes with a sample configuration file named "settings.ini". While this configuration is enough to start with, it's always a good idea to customize it to personal needs. 
     1101. Target Folder\\ \\The output folder should be changed to a more appropriate name and location. For example:\\{{{TargetFolder = D:\arinside_doc\<servername>}}}\\ \\ 
     1112. User List\\ \\If you have a lot of users it could increase the duration of a run significantly. At the same time you don’t get much functionality, just some details like license type and such, and a direct link between an AR-system object and the user. For most customers this isn’t important at all. In this case it’s recommended to disable loading of users.\\{{{# Data Retrieval}}}\\{{{LoadUserList = FALSE}}}\\ \\ 
     113== Security == 
     115ARInside uses the following ARSystem API calls to load objects from server / file. 
     117__Online Mode__ 
     118  ARInitialzation\\ 
     119  ARTermination\\ 
     120  ARGetList(...)\\ 
     121  ARGet(...)\\ 
     122  FreeAR\\ 
     124__File Mode__ 
     125  ARInitialzation\\ 
     126  ARGet(...)FromXML\\ 
     127  FreeAR\\ 
     129__Security Comments__ 
     130  ARInside doesn't use any of the {{{ARSet(…)}}} or {{{ARExecuteProcess}}} API calls. 
     132== Known Errors == 
     133Here are some known problems and possible workarounds listed. 
     135=== Loading of encryption library failed === 
     136In some cases the program prints out the following text right after the start: 
     139Connecting to server 
     140Initilization of ARAPI returned: 2 (Error) 
     141[ARERR 9011] Loading of encryption library failed 
     144After the error message, the program crashes. From what is known this is an issue of ARAPI 7.5, if it finds another api file within the path. The workaround is to clear the PATH variable before you run ARInside. 
     147C:\> set PATH= 
     150Reference: (#81) 
     152=== Page not rendered by Internet Explorer === 
     153It looks like "Internet Explorer" has some trouble rendering bigger html files. A user has had some trouble with a 60 MB html file. In such a case we can only recommend using another browser. Firefox and Chrome will work very well in such a case. 
     155=== Unicode Support === 
     156While there is an option named "UTF-8" within the {{{settings.ini}}} file, the functionality isn't finished yet. Currently, the setting doesn't have any impact. Unicode support will be added in the future. 
     158=== Communication with older server versions === 
     159The current release of ARInside uses a rather new version of ARAPI. If you connect to a server which has an older version, usually the API handles the backward compatibility. But we have observed some cases where the newer api-version couldn't handle the data transfer correctly. That’s mostly because ARInside uses some of the newer {{{ARGetMultiple(...)}}} api-calls which aren’t supported on AR Servers below version 6.3. Starting with ARInside 3.1.1 the slower object loading is automatically activated if you connect to a server below version 6.3. If ARInside causes crashes on newer server versions (6.3 and above) and prints some ARERR90 and ARERR91 during loading of objects like activelinks, filters, escalations, menus and so on, just use the "--slow" command line option. If this setting is specified, ARInside will load objects via calls like ARGetActiveLink (instead of ARGetMultipleActiveLinks) which provides a better backwards compatibility but is much slower. 
     161Reference: (#118) , (#133) 
     163== Troubleshooting == 
     164In case you observe some error during execution of ARInside (e.g. a crash) you should activate the detailed logging and redirect the output to a log file like this: 
     167arinside.exe [...] –v >arinside.log 2>&1 
     170The {{{[...]}}} is just a placeholder for other options (like –i) you want to specify on the command line. In this example the output is redirected to the file {{{arinside.log}}}.