Set Up the File Import Agent

The file import agent is a command-line application that runs on any computer and serves as the source for importing content from a monitored file system location such as a folder or network drive. It monitors and captures the content in that location and feeds it to the import processor for further processing and routing according to the rules defined in the procedure.

You need to install and run the file import agent on your local computer only if your source is a monitored folder (not a monitored email account). The capture command-line utility is available to help you register servers, configure import jobs, and list them.

Setting up the file import agent consists of these steps:

Download and Install the File Import Agent
Oracle is in the process of updating Oracle Cloud Infrastructure (OCI) regions to switch from Identity Cloud Service (IDCS) to Identity and Access Management (IAM) identity domains. All new Oracle Cloud accounts will automatically use IAM identity domains. Depending on whether your region uses IAM identity domains or not, you'll use different documentation to complete your setup.
- If your region has been updated, follow the steps in Create the Oracle Cloud Infrastructure Identity and Access Management (IAM) Domain Application.
- If your region hasn't been updated, follow the steps in Create the Oracle Identity Cloud Service (IDCS) Application.
Register Oracle Content Management with the File Import Agent
Use the Capture Command-Line Utility

Download and Install the File Import Agent

Before you can import files from a monitored folder, you need to install the file import agent on your local computer.

System Requirements

The file import agent is a Java application that needs Oracle JDK version 17 or the latest version available at the time you're going to install this application. The file import agent is compatible with Windows, Linux, and Mac (see Oracle JDK 17 Certified System Configurations).

To download and install the file import agent:

Log in to the Oracle Content Management web interface and click Capture in the left navigation panel (under Administration). If you don’t see this option, you don’t have the required access privileges.
On the Capture Procedures page, under Downloads, click Oracle Content Capture File Import Agent to download the capture-agent.zip file to your local computer.
Extract the ZIP file.
You must add <agent directory>\bin to PATH. The agent directory is the folder where capture-agent.zip is extracted. You can also set the CAPTURE_HOME environment variable to the extracted directory and add $CAPTURE_HOME\bin to PATH.
On Mac:
```
sudo ln -s <agent directory>/bin/capture /usr/local/bin/capture
```
On Windows:

Run the SystemPropertiesAdvanced.exe file, then edit Environment Variables, and then add <agent directory>\bin to the PATH variable.
Set the CAPTURE_JAVA_HOME variable to valid JDK location either as an environment variable or in the <agent directory>/conf/agent.properties file.

Register Oracle Content Management with the File Import Agent

Your Oracle Content Management instance must be registered with the capture command-line utility so the utility knows what import jobs are configured with the Oracle Content Management instance, and it can upload files to this instance.

To register Oracle Content Management:

Download and install the File Import Agent if you don't have it installed on your computer already.
Run one of these commands on your Windows, Linux, or Mac operating system:
```
$ capture register-server <NAME> --endpoint https://<oracle content management instance name>.oraclecloud.com -u username -p password --domainurl <REST Endpoint (Permanent)>/oauth2/v1/token --clientid sampleid --clientsecret sample-secret --scope https://<server name>:<port number>/urn:opc:cec:all
```
- Oracle Content Management instance URL: <oracle content management instance name>.oraclecloud.com
- User name and Password for your Oracle Content Management instance URL.
  
  Note:
  To mitigate a potential security threat, consider creating a file import agent-specific user that is assigned only the content capture roles or permissions on the required procedures.
- Oracle Identity Service Instance URL: <REST Endpoint (Permanent)>/oauth2/v1/token (You copied REST Endpoint (Permanent) at the time of creating the IDCS application. Or you copied its value when you created the IAM domain application if you've migrated your IDCS stripes to IAM identity domains.)
- Client ID: sampleid (You copied its value at the time of creating the IDCS application. Or you copied its value when you created the IAM domain application if you've migrated your IDCS stripes to IAM identity domains.)
- Client Secret: sample-secret (You copied its value at the time of creating the IDCS application. Or you copied its value when you created the IAM domain application if you've migrated your IDCS stripes to IAM identity domains.)
- Scope URL: https://<server name>:<port number>/urn:opc:cec:all (You copied its value at the time of creating the IDCS application. Or you copied its value when you created the IAM domain application if you've migrated your IDCS stripes to IAM identity domains.)
If you are using IDCS, alternatively get the IDCS token value:
```
$ capture register-server <NAME> --endpoint https://<oracle content management instance name>.oraclecloud.com --token <token value>
```
To get the token value, enter this URL from a browser: https://Content Management URL:port/documents/web?IdcService=GET_OAUTH_TOKEN
Note:
- The documents/web context is protected by Oracle Identity Cloud Services (IDCS). The user will be prompted to sign in to IDCS unless there is already a valid IDCS session in the browser.
- The OAuth token is returned in the tokenValue field in the JSON response. The token is valid for 7 days, and the expiration is in seconds.
Test your connection by running the command to list the import jobs:
```
$ capture list-import-jobs
```
A list of all folder and file list import jobs configured in capture procedures on the specified Oracle Content Management instance is displayed.

After you've registered Oracle Content Management and configured import jobs, configure file importing from a folder or configure list file importing.

Use the Capture Command-Line Utility

The capture command-line utility lets you configure the file import agent so the agent can import documents in to the Oracle Content Management repository. It provides commands for using and managing the file import agent.

------------------------
capture
------------------------
usage : capture <command> [options]
Run capture <command> -h' to get the detailed help for the command.
Commands:  
capture create-encryption-key <file>     Create an encryption key to encrypt/decrypt password for servers.       [alias:   cek]  
capture register-server <name>           Registers an Oracle Content Management server                           [alias:   rs]  
capture list-servers                     Lists registered servers                                                [alias:   ls]  
capture list-import-jobs                 Lists all Import Jobs from server                                       [alias:  lij]  
capture configure-import-job             Configures import job. Set Import Folder path. Enable or disable.       [alias:  cij]
capture configure-archiver-job           Configures archiver import job to import content from on-premise 
                                         WebCenter Content into Oracle Content Management                        [alias:  caj]
capture trigger-import-job               Forces import job processing.                                           [alias:  tij]
capture refresh-config                   Refresh configuration from server.                                      [alias:   rc]
capture list-procedures                  Displays capture procedures.                                            [alias:   lp]  
capture register-database <name>         Registers external database.                                            [alias:   rd]  
capture deregister-database              Deregister previously registered database.                              [alias:   dd]  
capture list-databases                   Displays registered databases and tables.                               [alias:   ld]  
capture register-table                   Registers tables in a database.                                         [alias:   rt]  
capture deregister-table                 Deregister previously registered table.                                 [alias:   dt]
capture list-table-sync-jobs             Lists all Asset Sync Jobs from server.                                  [alias: ltsj]
capture trigger-table-sync               Force table / asset synchronization.                                    [alias:  tts]
capture start                            Starts import agent                                                     [alias:    s]  
capture stop                             Stops import agent                                                      [alias:    x]  
capture status                           Shows import agent status                                               [alias:   st]  
capture help                             Shows this message                                                      [alias:    h]

-----------------------------
capture create-encryption-key
-----------------------------
usage: create-encryption-key <file> [-h]
Create an encryption key to encrypt/decrypt password for servers and save to <file>.
Options: 
-h,--help   Show help
Example:  
capture create-encryption-key ~/.ceckey                      Create encryption key and save to file ~/.ceckey
------------------------
capture register-server
------------------------
usage: capture register-server <name> -e <endpoint> -u <user> -p <password> [-k <key>] [-d <domainurl] 
[-c <clientid>] [-s <clientsecret>] [-o <scope>] [-t <token>] [-m <timeout>] [-x <proxy>]
Registers an Oracle Content Management server. 
Specify -e <endpoint> for the server URL. 
Specify -u <user> and -p <password> for connecting to the server. 
Optionally specify -k <key> to encrypt the password.
Optionally specify <domainurl>, <clientid>, <clientsecret> and, <scope> for integration with IAM application. 
Optionally specify <token> to use for authorization.

NOTE: -i and --idcsurl have been deprecated. For now they exist for backward compatibility but will be removed in a future release.

Options: 
-e,--endpoint <endpoint>           Server endpoint 
-u,--user <user>                   User name 
-p,--password <password>           Password 
-k,--key <key>                     The key file used to encrypt the password 
-d,--domainurl <domainurl>         Oracle Identity and Access Management Instance URL 
-c,--clientid <clientid>           Client ID 
-s,--clientsecret <clientsecret>   Client secret 
-o,--scope <scope>                 Scope
-t,--token <token>                 OAuth Token to use for authorization. 
-m,--timeout <timeout>             Timeout in millisecond for connections to the server. Defaults to 60 seconds
-x,--proxy <proxy>                 Set proxy host and port
-h,--help                          Show help
Examples:  
capture register-server server1 -e http://server1.com -u user1 -p password1 -d                   
The server is a tenant on Oracle Public cloud  
http://iam.com -c clientid -s clientsecret -o https://primary-audience-and-scope  
capture register-server server1 -e http://server1.com -u user1 -p password1                      
The server is a tenant on Oracle Public cloud  
capture register-server server1 -e http://server1.com -u user1 -p password1 -m 60000             
The timeout is set to 60 seconds  
capture register-server server1 -e http://server1.com -u user1 -p Welcome1 -x my_proxy_host:port 
The proxy is set to my_proxy_host:port
capture register-server server1 -e http://server1.com -u user1 -p Welcome1 -k ~/.mykey           
The password will be encrypted
capture register-server server1 -e http://server1.com -t <token value>                           
The token will be used for authorization
------------------------
capture list-servers
------------------------
usage: capture list-servers [-u <user>] [-f <pattern>] [-h]
Lists registered Oracle Content Management servers. Optionally specify -u <user> 
and -f <pattern> to filter results based on user or server name.
Options: -u,--user <user>         User name 
-f,--pattern <pattern>   String to search in server name 
-h,--help                Show help
Examples:  
capture list-servers                              Lists all registered servers  
capture list-servers -u user1                     Lists all registered servers linked to user 'user1'  
capture list-servers -f demo                      Lists all registered servers whose name contains 'demo'
------------------------
capture list-import-jobs
------------------------
usage: capture list-import-jobs [-f] [-l] [-h]
Lists all Import Jobs from server. Optionally specify -f and -l to show only folder or list file import jobs.
Options: 
-f,--folder     Display only folder import jobs 
-l,--listfile   Display only list file import jobs 
-h,--help       Show help
Examples:  
capture list-import-jobs                                         Lists all import jobs  
capture list-import-jobs -f                                      Lists all folder import jobs  
capture list-import-jobs -l                                      Lists all list file import jobs
-----------------------------
capture configure-import-job
-----------------------------
usage: capture configure-import-job -s <server> [-i <import>] [-p <path>] [-e] [-E] [-d] [-D] [-h]
Configures the import job.  Specify -s <server> -i <importjobid> to select the server and import job. 
Optionally specify -p <path> to set the import folder path. 
Optionally specify -d to disable import job and -e to enable import job
Options: 
-s,--server <server>   Set server name associated with import job 
-i,--import <import>   Set Import Job Id 
-p,--path <path>       Set Local Import Folder Path 
-e,--enable            Enables specific import job 
-E,--enable-all        Enables all import jobs 
-d,--disable           Disables specific import job 
-D,--disable-all       Disables all import job 
-h,--help              Show help
Examples:  
capture configure-import-job -s prod -i import_id -p /Users/user1/data/    Sets the import directory  
capture configure-import-job -s prod -i import_id -e                       Enables a specific import job  
capture configure-import-job -s prod -D                                    Disables all import jobs  
capture configure-import-job -s prod -i import_id -d                       Disables a specific import job
-----------------------------
capture configure-archiver-job
-----------------------------
capture configure-archiver-job -s <server> [-w <procedure>] [-p <path>] [-c <importjob> | -u <importjobid>] [-e | -d] [-h]

Specify -s <server> to select the server, -w <procedure_id> to select the procedure, 
-p <path_to_archiver_export> to select the path, 
-c <import_job_name> / -u <import_job_id> to create or update the import job.

Options:
 -s,--server <server>         Set server name associated with import job
 -w,--procedure <procedure>   Procedure identifier
 -p,--path <path>             Path to archiver output folder
 -c,--create <importjob>      Name of the new import processor Job
 -u,--update <importjobid>    Identifier of the import processor Job
 -e,--enable                  Enables specific import job
 -d,--disable                 Disables specific import job
 -h,--help                    Show help

Examples:
  capture configure-archiver-job -s prod -w procedure_id -c 'Import Job Name' -p /Users/user1/data/    
  Creates the import processor in the procedure and configures the import path
  capture configure-archiver-job -s prod -w procedure_id -u import_job_id -p /Users/user1/data/        
  Updates the import processor in the procedure
  capture configure-archiver-job -s prod -u import_job_id -d       
  Disables a specific import job
  capture configure-archiver-job -s prod -u import_job_id -e      
  Enables a specific import job
------------------------
capture trigger-import-job
------------------------
usage: capture trigger-import-job -s <server> -i <import> [-h] 
Forces import job processing.  
Options: 
-s,--server <server>   Set server name associated with import job 
-i,--import <import>   Set Import Job Id 
-h,--help              Show help 
Examples:  capture trigger-import-job --server production --import xx-job-id-xx       
Forces processing of specified import job
------------------------
capture refresh-config
------------------------
usage: capture refresh-config [-s <server>] [-h] Refresh configuration from server. 
Optionally specify -s to only refresh config for selected server. 
Options: 
-s,--server <server>   Specify the server 
-h,--help              Show help 
Examples:  
capture refresh-config                       Force refresh configuration for all servers  
capture refresh-config -s production         Force refresh configuration from specified server                        
------------------------
capture list-procedures
------------------------
usage: capture list-procedures -s <server> [-h] 
Lists capture procedures. Must specify -s <server> to select a server. 
Options: 
-s,--server <server>   Specify the server 
-h,--help              Show help 
Examples:  capture list-procedures -s ocetest      Lists all capture procedures available for current user
------------------------
capture register-database
------------------------
usage: capture register-database <name> -s <server> -w <procedure> -c <connection> -u <user> -p <password> [-a] [-h] 
Registers on-prem database with Content Capture. Specify -c <connection> for the connection URL, 
-u <user> and -p <password> for connecting to the server. 
Options: 
-s,--server <server>           Specify the server 
-w,--procedure <procedure>     Set procedure to be associated with database 
-c,--connection <connection>   Database connection url 
-u,--user <user>               Database User name 
-p,--password <password>       Database Password 
-a,--attach                    Attach existing database 
-h,--help                      Show help 
Examples:  
capture register-database ebsdb -s server1 -w 1 -c jdbc:oracle:thin:@//host:port/service -u user1 -p pass    
Register ebsdb with server1
------------------------
capture deregister-database
------------------------
usage: capture deregister-database  -s <server> -w <procedure> -d <database> [-e] [-h] 
Deregister previously registered database. Specify -s <server>, -w <procedure> and -d <database> to select the database. 
Options: 
-s,--server <server>         Specify the server 
-w,--procedure <procedure>   Procedure associated with database 
-d,--database <database>     Database to deregister 
-e,--detach                  Only detach 
-h,--help                    Show help 
Examples:  
capture deregister-database -s server1 -w 1 -d ebsdb                   Deregister VENDORS table from ebsdb database  
capture deregister-database -s server1 -w 1 -d ebsdb --detach          Detaches ebsdb database without deregistering it
------------------------
capture list-databases
------------------------
usage: capture list-databases -s <server> [-h] Lists registered databases and tables. Must specify -s <server> to select a server. 
Options: 
-s,--server <server>   Specify the server 
-h,--help              Show help 
Examples:  
capture list-databases -s ocetest     Lists all registered databased linked to server 'ocetest'  
------------------------
capture register-table
------------------------
usage: capture register-table -s <server> -w <procedure> -d <database> -t <table> [-m <schema>] [-h]
Registers table with Content Capture. Specify -s <server>, -w <procedure> and -d <database> to select the database. 
Options: 
-s,--server <server>         Specify the server 
-w,--procedure <procedure>   Specify the procedure 
-d,--database <database>     Specify the database 
-t,--table <table>           Table to sync 
-m,--schema <schema>         Override schema qualifier 
-h,--help                    Show help 
Examples:  
capture register-table -s server1 -w 1 -d ebsdb -t VENDORS   
Register VENDORS table from ebsdb database  
capture register-table -s server1 -w 1 -d ebsdb -t VENDORS -m SVR 
Register VENDORS table from ebsdb database in SVR schema
------------------------
capture deregister-table
------------------------
usage: capture deregister-table -s <server> -w <procedure> -d <database> -t <table> [-m <schema>] [-h] 
Deregister table. Specify table details. 
Options: 
-s,--server <server>         Specify the server 
-w,--procedure <procedure>   Procedure associated with database 
-d,--database <database>     Specify the database 
-t,--table <table>           Table to sync 
-m,--schema <schema>         Override schema qualifier 
-h,--help                    Show help 
Examples:  capture deregister-table -s server1 -w 1 -d ebsdb -t VENDORS 
Deregister VENDORS table from ebsdb database      
------------------------
capture list-table-sync-jobs
------------------------
usage: capture list-table-sync-jobs [-r] [-h] Lists all Asset Sync Jobs from server. 
Options: 
-r,--refresh   Force refresh asset sync jobs from server 
-h,--help      Show help 
Examples:  
capture list-table-sync-jobs               Lists all asset sync jobs  
capture list-table-sync-jobs -r            Refresh asset sync jobs from server and list them
------------------------
capture trigger-table-sync
------------------------
usage: capture trigger-table-sync -s <server> -a <asset> [-h] 
Force table / asset synchronization.  
Options: 
-s,--server <server>   Set server name associated with table sync job 
-a,--asset <asset>     Set Asset Sync Job Id 
-h,--help              Show help 
Examples:  
capture trigger-table-sync -s production -a xx-123-sync-id-xx      
Forces processing of asset synchronization job
------------------------
capture start
------------------------
usage: capture start [-h]
Starts capture agent. 
Options: 
-h,--help   Show help
Examples:  
capture start         Starts capture agent if not running
------------------------
capture stop
------------------------
usage: capture stop [-h]
Stops capture agent. 
Options: 
-h,--help   Show help
Examples:  
capture stop             Stops capture agent if currently running
------------------------
capture status
------------------------
usage: 
capture status [-s <server>] [-i <import>] [-u <user>] [-m <machine>] [-l <limit>] [-d <duration>] [-c | -p] [-h] 
Display capture agent status and activity.  
Options: 
-s,--server <server>       Set Server name 
-i,--import <import>       Set Import Job name 
-u,--user <user>           Set user name. Defaults to current user 
-m,--machine <machine>     Set host name. Defaults to current hostname 
-l,--limit <limit>         Set number of results to return. Defaults to 200 
-d,--duration <duration>   Set duration period in hours 
-c,--completed             Display only completed uploads 
-p,--pending               Display only pending uploads 
-h,--help                  Show help 
Examples:  
capture status                             Display capture agent status  
capture status -u user@example.com         Show upload activity for user : user@example.com  
capture status -i Invoices                 Show upload activity for Invoices import job  
capture status -m myhost.example.com       Show upload activity for a specific host / machine  
capture status -p                          Show uploads pending completion  
capture status -c                          Show completed uploads
------------------------
capture version
------------------------
usage: capture version [-h] 
Displays capture version details. 
Options: 
-h,--help    Show help 
Example:  
capture  version  
Display capture agent version