16 Oracle Healthcare Command-Line Tools

This chapter describes the Oracle Healthcare command-line tools that are available for a number of tasks such as purging data, importing and exporting data, batching operations, updating and deleting endpoints, and so on.

This chapter contains the following topics:

16.1 Prerequisites for Running the Command-line Tools

Do the following before using the command-line tools:

  1. Set the ORACLE_HOME, ANT_HOME, and JAVA_HOME environment variables.

    ORACLE_HOME is set to your Oracle SOA Suite install in the Oracle Fusion Middleware installation directory. For example if the default shell is CSH:

    setenv ORACLE_HOME <Oracle SOA install directory>
    setenv ANT_HOME $ORACLE_HOME/../modules/org.apache.ant_1.7.1 
    set JAVA_HOME $ORACLE_HOME/<jdk install directory> 
    
  2. Create jndi.properties.

    cd $ORACLE_HOME/bin
    ant -f ant-hcfp-util.xml hcfpcreate-prop
    
  3. Edit the jndi.properties file to include the weblogic password.

Notes:

1. Command-line tools are for administrator use only. No security or permission checks are performed to prevent the logged-in user from purging, importing, or exporting data.

2. After running any command-line tool, you should gain log on to the Oracle Healthcare console. The Oracle Healthcare console caches some metadata and any command-line action which may have updated the metadata could lead to invalid cached data. Therefore, it is advisable to always re-login into the Oracle Healthcare console after using command-line operations.

3. All of the command-line tools can be run without any JNDI credentials. To restrict the command-line tools from anonymous use, provide the following information in the jndi.properties file:

java.naming.security.principal=weblogic
java.naming.security.credentials=weblogic_password

Note:

For any Oracle Healthcare command-line utility, by default, the ANT run shows BUILD SUCCESSFUL and system code 0 (zero) is returned even in the case of client or server side error. In case you want the ANT run to FAIL for each client or server side error, then you need to set exitonerror parameter to true.

You can do this in either of the following two ways:

  • Specify -Dexitonerror=true on ANT command line

    ant -f ant-hcfp-util.xml b2bpurge -Dagreement=<AGR_NAME> -Dmode=DT -Dexitonerror=true
    
  • Setting the exitonerror parameter as global setting:

    Create a properties file called ant_general.properties with the value exitonerror=true in the directory where ant-hcfp-util.xml is present ($ORACLE_HOME/bin).

With this configuration, for all client or server errors, all ANT commands will fail with the message BUILD FAILED and the system exit code will be set to -1.

16.2 Purging Data

This utility is used to purge design and runtime data from the Oracle Healthcare repository. This utility also provides the archiving feature by default. If Archive is set to YES, then the an initial setup is required.

To do initial setup:

  1. On the machine running the database, create a directory in which to dump the archive file. For example:

    mkdir /tmp/archive
    
  2. Grant permissions to this directory so that the database process can write to it.

    chmod 777 /tmp/archive
    
  3. Log in to the database as sysdba.

    sqlplus / as sysdba
    
  4. Set up the HCFP_EXPORT_DIR.

    SQL> create or replace DIRECTORY HCFP_EXPORT_DIR as '/tmp/archive'
    
  5. If your SOA schema user is hcfp_soainfra, the user needs to be granted permission for the export.

    SQL> grant read, write on directory HCFP_EXPORT_DIR to hcfp_soainfra;
    SQL> grant exp_full_database  to hcfp_soainfra;
    

The following utility purges both design-time and runtime data and resets the environment to the installation time.

ant -f ant-hcfp-util.xml hcfppurge

Table 16-1 lists the options for this utility.

Table 16-1 Options for hcfppurge utility

Option Description Domain Required
mode

Specifies purging design-time or runtime data (see Note below).

Runtime options: msgstate/start/end/purgecontrolnumber

Design-time options: host

DT
RT

Yes

msgState

Deletes messages with the specified message state. Used for runtime data.

MSG_COMPLETE
MSG_ERROR
MSG_WAIT_TRANSMIT
MSG_WAIT_FA
MSG_WAIT_BATCH

No. If msgstate is present, then start and end must be used.

purgecontrolnumber

Deletes control numbers. Used for runtime data.

true

false (default)

No

fromdate

Deletes all messages, which created on or after this date.

Date format

dd/mm/yyyy hh:mm AM/PM

No

todate

Deletes all messages, which created on or before this date.

Date format

dd/mm/yyyy hh:mm AM/PM

No

direction

Direction of the message

 

No

msgtype

Type of the message

 

No

archive

Should archive

 

Default value is true

archivename

File name of archived file

 

No


Note:

When only -Dmode=RT -Dtp=endpoint_name options are used, this option deletes all records matching endpoint name with SenderName or in Receiver Name.

Example 16-1 Removes Design-Time Data

ant -f ant-hcfp-util.xml hcfppurge -Dmode=DT

Example 16-2 Purges runtime Data

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Darchive=false

Example 16-3 Purges runtime Data, Including Control Numbers

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Dpurgecontrolnumber=true

Example 16-4 Purges Messages with the Specified State Between the Specified Dates

ant -f ant-hcfp-util.xml hcfppurge -Dmode=RT -Dfromdate="01/02/2009 12:00 AM" -Dtodate="10/02/2009 12:00 AM" -Dmsgstate=MSG_COMPLETE -Darchive-false

Note:

When using archivename the value must be a unique file name. An existing file name used with archivename throws an exception.

16.3 Importing Data

Note:

No security or permission checks are performed to prevent the logged-in user from importing data.

The hcfpimport utility imports the Oracle Healthcare metadata ZIP file to the repository. Basic validation is performed, but it is not a complete validation as with deployment validation. No data is overwritten unless you use the overwrite option.

The following usage imports data from tmp/export.zip to a location on the same server without overwriting.

ant -f ant-hcfp-util.xml hcfpimport -Dlocalfile=true -Dexportfile="/tmp/export.zip"

Table 16-2 lists the options for this utility.

Table 16-2 Options for hcfpimport utility

Option Description Domain Required
exportfile

Location of the export (ZIP) file

-

Yes

overwrite

Overwrites the existing business elements. For example, an existing endpoint with the same endpoint name as an endpoint in the import file is replaced if this option is set to true.

true

false (default)

No

localfile

If the export file location exists on the server, then set this option to true to improve performance. The export file must be on the server on which Oracle Healthcare is running.

true

false (default)

No

active

Enable all the endpoints after import

true

false (default)

No


16.4 Exporting Data

The hcfpexport utility exports metadata from the Oracle Healthcare repository. If no options are specified, then the entire repository is exported.

Note:

No security or permission checks are performed to prevent the logged-in user from exporting data.

The following usage exports the entire repository (without policy details) to /tmp/export.zip if no other options are specified.

ant -f ant-hcfp-util.xml hcfpexport

Table 16-3 lists the options for this utility.

Table 16-3 Options for hcfpexport utility

Option Description Domain Required
exportfile

Location of the ZIP file where the exported data is stored

/tmp/export.zip (default)

No

endpoint

Name of the endpoint

 

No

policies

Set to true to export the entire repository with user and role details, which is needed for the policy store. A warning is displayed to remind you to export the policy store also.

true

false (default)

No

localfile

Set to true for improved performance if the export file is on the same computer as Oracle Healthcare.

true

false (default)

No


Example 16-5 Exports entire repository with policy details to /tmp/export.zip

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/export.zip" -Dpolicies=true

Example 16-6 Exports entire repository w/o details to /tmp/exportinserver.zip on same server

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/exportinserver.zip" -Dlocalfile=true

Example 16-7 Exports the Endpoint Admission to /tmp/export.zip

ant -f ant-hcfp-util.xml hcfpexport -Dexportfile="/tmp/export.zip" -Dendpoint=Admission

16.5 Batching Operations

The command line hcfpbatch utility enables you to create and delete batches, based on various criteria. This is an ANT-based command, and provides the flexibility to selectively set the criteria to create batches.

The usage is as follows:

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=<EndpointName> -Dbatchtime=<batchTriggerTime> -Dbatchname=<batchName> -Ddocument=<documentProtocolName> -Ddocrevision=<docRevision> -Ddoctype=<docType> -Disrepetitive=<true|false>

Table 16-4 lists the options for this utility.

Table 16-4 Options for hcfpbatch utility

Option Description Domain Required

endpoint

Endpoint name.

Specify the endpoint name.

YesFoot 1 

batchname

Batch name.

Specify a name for the batch.

Yes

batchtime

Batch trigger time.

The trigger time can be a cron String or the date in
dd/MM/yyyy HH:mm AM/PM format.

Yes

document

Document Protocol name.

Valid values:
EDI_EDIFACT, EDI_X12

Yes

docrevision

Document revision.

-

Yes

doctype

Document type.

-

Yes

isrepetitive

To enable repetitive batching when batch is created using cron string.

Valid values: true or false

No

mode

Mode

Set to deletebatch to delete the batch.

No


Footnote 1 To create a batch the endpoint, batchtime, batchname, document, docrevision, doctype options are required, to delete a batch only the mode and batchname options are required.

Note:

While creating a cron job for the commandline operation, you need to follow the cron syntax.

Example 16-8 Creates a batch operation

This command creates a batch operation with FileEndpoint for the X12/4010/850 document that is executed in a repetitive mode for the given cron String.

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="0 4850 11 7 5 ? 2010" -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype=850 -Disrepetitive=true

Example 16-9 Creates batches for multiple document types

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="0 58 11 7 5 ? 2010" -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype=850,997

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime="07/05/2010 11:45 AM" -Dbatchname=batch1234 -Ddocument=X12 -Ddocrevision=4010 -Ddoctype=850,997

Example 16-10 Deletes a batch operation

ant -f ant-hcfp-util.xml hcfpbatch -Dmode=deletebatch -Dbatchname=batch1234 

Example 16-11 Using special characters in batchtime option

If the value for the batchtime contains special characters such as * or #, then the character must be escaped using double quotation marks.

ant -f ant-hcfp-util.xml hcfpbatch -Dendpoint=FileEndpoint -Dbatchtime='0 5,10,15,20,25,30,35,40,45,50,55,59 "*" "*" "*" ? 2010' -Dbatchname=batch1234 -Ddocument=EDI_X12 -Ddocrevision=4010 -Ddoctype="850,855" -Disrepetitive=true 

16.6 Resubmitting a Message

The following utility resubmits an application message or a wire message for a selected business message.

ant -f ant-hcfp-util.xml hcfpresubmit

Note:

The resubmit functionality for payload rectification will only work for Outbound Message for AppMessage only. This is not valid for inbound cases.

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dmsgid=12345 -Dpayloadpath=/scratch/<username>/fmwhome/AS11gR1SOA/bin/3a4_req.xml

Table 16-5 lists the options for this utility.

Table 16-5 Options for hcfpresubmit utility

Option Description Domain Required
direction

The direction of the message

INBOUND

OUTBOUND

No

msgsource

The message source

APPMSG (Default)

WIREMSG

Yes

msgid

The message ID

Can be multiple message IDs separated by comma

 

doctype

Document Type

   

msgstate

Message State

   

fromdate

The sendTimestamp of the message

Date format to be provided within Double Quotes

dd-mm-yyyy hh:mm AM/PM 

Note: This cannot be a future date.

 

todate

The sendTimestamp of the message

Date format to be provided within Double Quotes

dd-mm-yyyy hh:mm AM/PM 

Note: todate should be greater than fromdate. You can provide both the dates.

 

payloadpath

This option is applicable for outbound application message resubmission, by providing the rectified file path.

   

Example 16-12 Resubmits an Outbound Message with Message ID 12345

ant -f ant-hcfp-util.xml hcfpresubmit -Ddirection=OUTBOUND -Dmsgsource=APPMSG -Dmsgid=12345\

Other Examples

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Ddoctype=850

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM"

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=WIREMSG -Dmsgstate=MSG_ERROR

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=OUTBOUND

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dfromdate="29/11/2009 5:40 AM" -Dtodate="30/11/2009 7:39 AM" -Ddirection=INBOUND

ant -f ant-hcfp-util.xml hcfpresubmit -Dmsgsource=APPMSG -Dmsgid=12345 -Dpayloadpath="/tmp/850.xml"

16.7 Scheduling Endpoint Downtime

Various Endpoint parties schedule their downtimes for different reasons and notify their partners about the downtime. During a downtime, parties sending the messages might not reach the destination. Scheduling the Endpoint downtime ensures that the messages are not delivered during that period, yet the messages are processed by Oracle Healthcare so that the messages are ready for delivery when the Endpoint party comes up after the downtime.

The following utility schedules downtime for an endpoint.

ant -f ant-hcfp-util.xml hcfpschedule

Table 16-6 lists the options for this utility.

Table 16-6 Options for hcfpschedule utility

Option Description Domain Required

mode

Indicates if the script will schedule or unschedule a downtime.

schedule (default)

unschedule

Yes

schedulename

A descriptive name for the scheduled downtime

-

Yes

endpoint

Endpoint name

-

Yes

(except in unschedule mode)

fromdate

The date and time at which to begin the downtime.

Date format to be provided within Double Quotes

dd/mm/yyyy hh:mm AM/PM 

No

todate

The date and time at which to end the downtime.

Date format to be provided within Double Quotes

dd/mm/yyyy hh:mm AM/PM 

No

extend

Extends a previously created schedule.

true

No


The following are examples of scheduling endpoint downtime using the hcfpschedule utility. The command does not need to be in a single line.

Example 16-13 Schedules endpoint downtime for all channels of GlobalChips from "14/05/2010 00:14 AM" to "14/05/2010 00:17 AM"

ant -f ant-hcfp-util.xml hcfpschedule
-Dendpoint="GlobalChips"
-Dfromdate="14/05/2010 00:14 AM"
-Dtodate="14/05/2010 00:17 AM"
-Dschedulename= "Maintenance"

Example 16-14 Un-schedules the scheduled event

ant -f ant-hcfp-util.xml hcfpschedule
-Dmode=unschedule
-Dschedulename="Maintenance"

16.8 Updating Endpoints

The following utility enables you to change an endpoint from active to inactive state or vice-versa:

ant -f ant-hcfp-util.xml hcfpupdateendpoint

Table 16-7 lists the options for this utility.

Table 16-7 Options for hcfpupdateendpoint utility

Option Description Domain Required
endpoint

The name of the endpoint

Specify the endpoint name

Yes

active

To make the endpoint active

true

false

Yes


Example 16-15 Updates an endpoint from the inactive to active state

ant -f ant-hcfp-util.xml hcfpupdateendpoint -Dendpoint=FileEndpoint -Dactive=true

16.9 Deleting Endpoints

The following utility deletes an endpoint.

ant -f ant-hcfp-util.xml hcfpdeleteendpoint

Table 16-8 Options for hcfpdeleteendpoint utility

Option Description Domain Required
endpoint

The name of the endpoint

Specify the endpoint name

Yes


Example 16-16 Deletes an endpoint from the inactive to active state

ant -f ant-hcfp-util.xml hcfpdeleteendpoint -Dendpoint=FileEndpoint