Guest

Cisco IP Interoperability and Collaboration System

Cisco IPICS 4.5 Command Line Interface Reference Guide

  • Viewing Options

  • PDF (281.5 KB)
  • Feedback
Cisco IPICS 4.5 Command Line Interface Reference Guide

Table Of Contents

Cisco IPICS 4.5 Command Line Interface Reference Guide

Using the CLI Commands

Bulk Channels Import Command

Bulk Channels Remove Command

Bulk Users Import Command

Bulk Users Remove Command

VSOM Import Command

VSOM Remove Command


Cisco IPICS 4.5 Command Line Interface Reference Guide


The Cisco IPCIS Command Line Interface (CLI) provides commands for updating Cisco IPICS via the bulk addition and removal of channels, users, and links to Cisco Video Surveillance Operations Manager (VSOM) video feeds.

This document describes each CLI command in detail.

Contents

Using the CLI Commands

Bulk Channels Import Command

Bulk Channels Remove Command

Bulk Users Import Command

Bulk Users Remove Command

VSOM Import Command

VSOM Remove Command

Using the CLI Commands

To use a CLI command, access the Cisco IPICS server via a secure shell (SSH) client and log in as the ipicsadmin user. Then, run the command in the home directory.

In a Cisco IPICS high-availability (HA) deployment, you can run a CLI command on the primary or on the secondary server. The Cisco IPICS updates that result from the command synchronize with the other server automatically. If one of the HA servers is offline when you run a command, the synchronization occurs when the offline server comes back on line. To ensure that synchronization occurs properly, do not run a CLI command when Cisco IPICS is in a split brain scenario. For related information about HA, see Cisco IPICS Server Administration Guide.

Bulk Channels Import Command

The CLI Bulk Channels Import command, ipics_import_channels, lets you add up to 5,000 channels to Cisco IPICS in a single transaction. This command imports an input file, which is a file in Comma-Separated Value (CSV) format that defines the channels to add.

When you execute the Bulk Channels Import command, the system validates each record in the input file. Records that pass the validation process are imported. Records that do not pass the validation process are rejected and saved in a Rejected file.

In addition, records that define channels that already exist in Cisco IPICS are rejected and information about these channels is not affected in Cisco IPICS.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_import_channels{--help |--csv CSV_file |--sample sample_file}

Syntax Description

--help

Displays help text for this command.

--csv

Imports the specified input file, which is a CSV file that defines the channels to be added to Cisco IPICS.

CSV_file

Name of the CSV input file that defines the channels to add.

The file must adhere to the guidelines that the "Input File" section describes.

Include the path if the file is not in the current folder.

--sample

Creates a CSV file that includes the headings of the fields that an input file requires.

You can use this sample file as a basis for the input file as described in the "Input File" section.

sample_file

Name of the sample file.

By default, the system saves the sample file in the current folder. To save it in another folder, include the path to that folder.


Input File

An input file that you use with the Bulk Channels Import command includes one record for each channel that is to be added to Cisco IPICS.

Cisco recommends that you use Microsoft Excel to create an import file, then use the Save As command in Excel to save the file as a CSV (Comma delimited) type.


Tip Run the Bulk Channels Import command with the --sample option to create a sample file that you can open with Microsoft Excel and use to create an input file.


An input file must adhere to these guidelines:

The file must be comma delimited.

The file can contain up to 5,000 records. If a file contains more than 5,000 records, the Bulk Channels Import command rejects the file.

Lines preceded with a semicolon (;) are comment lines and are ignored by the import process.

The pipe character (|) cannot be used in any line in the file.

Each record must include each field that Table 1 describes. The fields must be in the order shown. In this table, the "Required" column indicates whether a field must contain data. Fields that are not required can be blank.

For more detailed information about the channel configuration options, see the "Viewing and Editing Channel Details" section in Cisco IPICS Server Administration Guide.

Table 1 CSV File Format for Bulk Channels Import 

Field Name
Required
Description

CHANNEL NAME

Yes

Full name of the channel.

This value is case insensitive. The system converts each character to lower case.

SHORT NAME

Yes

Short name of the channel that appears in the Cisco IPICS Dispatch Console.

This value is case insensitive. The system converts each character to lower case.

The short name can contain up to 5 characters.

DESCRIPTION

No

Description of this channel.

SECURE

No

Designates whether the channel is secure.

Valid values are:

T—True (channel is secure)

F—False (channel is not secure)

The default value is F.

ALLOW USE IN VTG?

No

Designates whether the channel can be used in a VTG.

Valid values are:

T—True (channel can be used in a VTG)

F—False (channel cannot be used in a VTG)

The default value is T.

ALLOW ASSOCIATION TO USERS?

No

Designates whether the channel can be associated with a user.

Valid values are:

T—True (channel can be associated with a user)

F—False (channel cannot be associated with a user)

The default value is T.

OPS VIEW NAME

No

Name of an existing opsview to which the channel will belong.

The default value is SYSTEM.

LOCATION

No

Name of an existing location to be associated with the channel.

The default value is ALL.

MULTI-CAST IP ADDRESS

Yes

Unused multicast IP address in the format 239.x.x.x to be used for the media connection assignment for this channel. The last octet must be an even number.

If this multicast address does not exist, the system creates it.

PORT NUMBER

Yes

Port number of the multicast address.

Valid values are integers 21000 through 65534.

CODEC

Yes

Codec to be used by the channel.

Valid values are:

G.711

G.729

IDC RX MUTE

No

Designates how the receive mute functionality is configured on the Cisco IPICS Dispatch Console for this channel.

Valid values are:

CHANNEL—When PTT is engaged for this channel, incoming audio is muted for this channel only

ALL—When PTT is engaged for this channel, incoming audio is muted for all resources

NONE—When PTT is engaged for this channel, this channel is not muted when it receives audio

The default value is CHANNEL .

IDC ENABLE VAD

No

Designates whether VAD is used by the Cisco IPICS Dispatch Console when communicating with this channel.

Valid values are:

T—True (enable VAD)

F—False (do not enable VAD)

The default value is F.

IDC ALLOW LATCH

No

Designates whether a Cisco IPICS Dispatch Console user can use the latch functionality for this channel.

Valid values are:

T—True (allow latch)

F—False (do not allow latch)

The default value is F.

IDC LISTEN ONLY

No

Designates whether listen-only is enabled for this channel. When listen-only is enabled, a Cisco IPICS Dispatch Console user can hear but cannot talk on the channel.

Valid values are:

T—True (enable listen only)

F—False (do not enable listen only)

The default value is F.

IDC CHANNEL COLOR

No

Designates the color tag that is used for the display of the channel in the Cisco IPICS Dispatch Console.

Valid values are:

NOT COLORED

BLUE

GREY

GREEN

PINK

PURPLE

RED

YELLOW

The default value is NOT COLORED.

IDC CHANNEL REGION

No

Region in which the channel appears in the Cisco IPICS Dispatch Console.

Valid values are integers 1 through 6.

The default value is 6.


Import Summary

When the bulk channels import process completes, the system displays a summary of the import transaction. Example 1 shows a sample summary.

Example 1 Bulk Channels Import Summary

SSUMMARY
========================================
Input filename                          : upload_source_csv/bulk_upload_perm_channels.csv
----------------------------------------
# records in file                       : 60
# comment records skipped               : 24
# data records                          : 36
# channel name or shortname too long    : 1
# duplicate channel names in file       : 0
# duplicate channel shortnames in file  : 0
# duplicate media mcast in file         : 0
# mcast assignment already in use       : 0
# channel already in-use                : 0
# channel shortname already in use      : 0
# missing media connection attributes   : 0
# duplicate media connection assignment : 0
# duplicate media connection in file    : 0
# invalid media connection location     : 0
# invalid media connection multicast IP : 1
# invalid media connection port         : 20
# invalid media connection CODEC        : 1
# invalid opsview                       : 1
# invalid region                        : 0
# invalid color                         : 0
# invalid IDC MUTE RX                   : 1
# invalid channel information values    : 8
# Available LMR ports exceeded          : 0
# records to be imported                : 3
# records imported                      : 3
----------------------------------------
Results
----------------------------------------
UNSUCCESSFUL - See ipics_import_channels.ipicsadmin.rejected.txt for records rejected
             - See ipics_import_channels.ipicsadmin.accepted.txt for records accepted
 
   

If exceptions occur during the import process, the summary includes a description of each exception. These descriptions can include the following:

# Available LMR ports exceeded         : 
# channel already in-use               : 
# channel name or shortname too long   : 
# channel shortname already in use     : 
# duplicate channel names in file      : 
# duplicate channel shortnames in file : 
# duplicate media assignment           : 
# duplicate media assignment in file   : 
# duplicate media mcast in file        : 
# invalid channel information values   : 
# invalid color                        : 
# invalid IDC MUTE RX                  : 
# invalid media CODEC                  : 
# invalid media location               : 
# invalid media mcast address          : 
# invalid media mcast port             : 
# invalid opsview                      : 
# invalid region                       : 
# mcast assignment already in use      : 
# missing media assignment attributes  : 
Output Files

The Bulk Channels Import command generates one or both of these output files each time it executes. Each file is stored in the folder from which you execute the command.

Accepted file—Named ipics_import_channels.ipicsadmin.accepted.txt. This file includes each record that was imported into Cisco IPICS.

Rejected file—Named ipics_import_channels.ipicsadmin.rejected.txt. This file includes each record that was rejected by the import process.

Each output file is in Pipe-Separated Value (PSV) format and can be opened in Microsoft Excel by specifying the pipe character (|) as the delimiter when you open the file. These files show the records in the same format as in the input file, with the following fields added to the beginning of each record:

REASON—In the Accepted file, shows "RECORD IMPORTED." In the Rejected file, shows the reason that a record was rejected.

REF #—Internal reference number.

Importing Rejected Records

If the Bulk Channels Import command generates a Rejected file, you can perform the following procedure to import the rejected records:

Procedure


Step 1 Use Microsoft Excel to open the ipics_import_channels.ipicsadmin.rejected.txt file.

Make sure to specify the pipe character as the delimiter when you open the file.

Step 2 Correct the issues that are reported in the REASON field for each record.

Step 3 Delete the REASON and the REF # columns from the spreadsheet.

Step 4 Use the Save As command in Excel to save the file as a CSV (Comma delimited) type.

Step 5 Use the Bulk Channels Import command to import this CSV file.


Bulk Channels Remove Command

The CLI Bulk Channels Remove command, ipics_remove_channels, lets you remove from Cisco IPICS a designated channel or channels that are defined in either of these input files:

A CSV file, including a CSV file that you used with a previous execution of the Bulk Channels Import Command

An Accepted file that was generated by a previous execution of the Bulk Channels Import command

The Bulk Channels Remove command also lets you resolve channel data inconsistencies that occur due to an interruption of the bulk channels import process.

By using the most recently generated Accepted file as the input file when you run this command, you can conveniently reverse the last bulk channels import procedure that was performed.

The Bulk Channels Remove command immediately removes each designated channel, regardless of the current state or association of the channel.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_remove_channels{--channel channel_name |--csv CSV_file |--pipe PSV_file |--repair}

Syntax Description

--channel

Removes one designated channel.

channel_name

Name of the channel to remove.

--csv

Removes the channels that are defined in the designated CSV input file.

CSV_file

Name of the CSV file that defines the channels to remove.

The file must adhere to the guidelines that the "Input File" section describes.

Include the path if the file is not in the current folder.

--pipe

Removes the channels that are defined in the designated PSV input file.

PSV_file

Name of an Accepted file that was generated by the Bulk Channels Import command. See the "Output Files" section for more information about this file.

Include the path if the file is not in the current folder.

--repair

Resolves channel data inconsistencies that occur due to an interruption of the the import process.


Remove Summary

When the channels remove process completes, the system displays a summary of the operation. The remove summary shows the following information, as applicable:

Names of channels that were not removed and the reasons that they were not removed

Names of channels that were removed

Bulk Users Import Command

The CLI Bulk Users Import command, ipics_import_users, lets you add or update information about up to 100,000 users to Cisco IPICS in a single transaction. This command can import an input file, which is a file in Comma-Separated Value (CSV) format that defines the users to add, or a file in LDAP Data Interchange Format (LDIF) that defines the users to add or update.

This command also lets you perform a direct LDAP import operation, which adds users directly from an LDAP server. And you can activate or deactivate a recurring LDAP import process that automatically performs a direct LDAP import operation at regular intervals.

The following guidelines apply to this command:

When you execute the Bulk Users Import command, the system validates each record in the input file. Records that pass the validation process are imported. Records that do not pass the validation process are rejected and saved in a Rejected file.

Importing a CSV file configures in Cisco IPICS a wide variety of information for each user who is added. Importing an LDIF file or using the recurring LDAP import process configures in Cisco IPICS only the following items for each user who is added:

Login ID—Identified by the LDAP column name identifier

First name—Identified by the LDAP column name givenName

Last name—Identified by the LDAP column name sn

Before you can import an LDIF file, the Use LDAP Authentication option in the Cisco IPICS Administration Console must be enabled for the ops view to which the imported users will belong. For more information, see the "Adding Ops Views" section in Cisco IPICS Server Administration Guide.

The direct LADP import and recurring LDAP import operations support non-SSL encrypted LDAP authentication only. If your LDAP server supports an SSL encrypted port only, use the option for importing an LDIF file with the Bulk Users Import command.

The LDAP import configuration options controls several aspects of the direct LDAP import and the recurring LDAP import operations. You can view and update these options as described in the "Configuring LDAP Users Import Options" section.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_import_users{--help |--set_max_users |--csv CSV_file |
--ldif LDIF_file --login_identifier identifier --opsview name |--ldapimport |
--ldapimport_on |--ldapimport_off |--ldapimport_config |--sample sample_file}

Syntax Description

--help

Displays help text for this command.

--set_max_users

Sets the maximum number of users that can be imported at one time by the Bulk Users Import command. If an operation attempts to import more records than this option allows, the operation aborts and no users are imported.

When you execute the Bulk Users Import command with this option, the system displays the value that is configured currently and prompts you for a new value. To set a new value, enter the value, press the Enter key, then type y and press the Enter key again to confirm.

Valid values are integers 1 through 100000. The default value is 5000.

--csv

Imports the specified input file, which is a CSV file that defines the users to be added to Cisco IPICS.

CSV_file

Name of the CSV input file that defines the users to add.

The file must adhere to the guidelines that the "CSV Input File" section section describes. If this file includes records that define users who already exist in Cisco IPICS, those records are rejected and information about those users is not affected in Cisco IPICS.

Include the path if the file is not in the current folder.

--ldif

Imports the specified input file, which is an LDIF file that defines the users to be added to Cisco IPICS.

The LDIF file contains user information that has been exported from the LDAP server.

LDIF_file

Name of the LDIF input file that defines the users to add or update.

If the file includes existing Cisco IPICS users, they are handled as follows:

Users who do not use LDAP for authentication are not affected by the import process

Users who use LDAP for authentication have their first name and last name updated in Cisco IPICS with the information from the LDAP server

Users who use LDAP for authentication but who are not configured in the LDAP server and who do not have the Cisco IPICS All or System Administrator role are removed from Cisco IPICS if they belong to the ops view that is designated with the --opsview option

Include the path if the file is not in the current folder.

--login_identifier

Indicates that the following value is the name of the LDAP column that identifies the login IDs of users.

identifier

Name of the LDAP column that identifies the login IDs of users.

--opsview

Indicates that the following value is the name of the ops view to which the users you are importing will belong.

name

Name of the ops view to which the users you import will belong.

The ops view must already exist and the Use LDAP Authentication option must be enabled for it in Cisco IPICS Administration.

--ldapimport

Executes the direct LDAP import process, which adds to or updates in Cisco IPICS the users from designated the LDAP server, based on the designated LDAP search base and search filter. The LDAP server, search base, and search filter are defined by LDAP import configuration options.

The --ldapimport option configures in Cisco IPICS only the first name, last name, and login name of each user who is added.

If this option imports existing Cisco IPICS users, they are handled as follows:

Users who do not use LDAP for authentication are not affected by the import process

Users who use LDAP for authentication have their first name and last name updated in Cisco IPICS with the information from the LDAP server

Users who use LDAP for authentication but who are not configured in the LDAP server and who do not have the Cisco IPICS All or System Administrator role are removed from Cisco IPICS if they belong to the ops view that is configured for the LDAP import process

For information about the LDAP import configuration options, see the "Configuring LDAP Users Import Options" section.

--ldapimport_on

Immediately adds to Cisco IPICS the users from the LDAP server that is designated by an LDAP import configuration option and activates the automatically recurring LDAP import process.

After you activate the recurring LDAP import process, the system executes the import at 15 and 45 minutes past each hour.

--ldapimport_off

Deactivates the automatically recurring LDAP import process.

--ldapimport_config

Lets you view and update LDAP configuration options.

For detailed information about these options, see the "Configuring LDAP Users Import Options" section.

--sample

Creates a CSV file that includes the headings of the fields that an input file requires.

You can use this sample file as a basis for the input file as described in the "CSV Input File" section.

sample_file

Name of the sample file.

By default, the system saves the sample file in the current folder. To save it in another folder, include the path to that folder.


CSV Input File

A CSV input file that you use with the Bulk Users Import command includes one record for each user that is to be added Cisco IPICS.

Cisco recommends that you use Microsoft Excel to create an import file, then use the Save As command in Excel to save the file as a CSV (Comma delimited) type.


Tip Run the Bulk Users Import command with the --sample option to create a sample file that you can open with Microsoft Excel and use to create a CSV input file.


An input file must adhere to these guidelines:

The file must be comma delimited.

The file can contain up to 100,000 records. If a file contains more than 100,000 records, the Bulk Users Import command rejects the file.

Lines preceded with a semicolon (;) are comment lines and are ignored by the import process.

The pipe character (|) cannot be used in any line in the file.

Each record must include each field that Table 2 describes. The fields must be in the order shown. In this table, the "Required" column indicates whether a field must contain data. Fields that are not required can be blank.

Many of the field values must conform to requirements that are configured in the Cisco IPICS Administration Console. For more detailed information about the user configuration options, Cisco IPICS Server Administration Guide.

Table 2 CSV File Format for Bulk Users Import  

Field Name
Required
Description

LOGIN NAME

Yes

Cisco IPICS login name of the user.

This value is case insensitive. The system converts each character to lower case.

FIRST NAME

Yes

First name of the user.

LAST NAME

Yes

Last name of the user.

PASSWORD

No

Cisco IPICS login password of the user.

This value is case sensitive.

The default value is Welcome!23.

DIGIT ID FOR CISCO UNIFIED IP PHONE

No

Numeric ID that the user enters when accessing the Cisco IPICS service from a Cisco Unified IP Phone or when accessing the Cisco IPICS telephony user interface.

This field accepts numeric characters only.

DIGIT PASSWORD (PIN) FOR CISCO UNIFIED IP PHONE

No

Password that the user enters when accessing the Cisco IPICS service from a Cisco Unified IP Phone or PIN that the user enters when accessing the Cisco IPICS telephony user interface.

This field accepts numeric characters only.

IDC DIALER PHONE NUMBER

No

Unique number that the Cisco IPICS Dispatch Console requires to register with Cisco Unified Communications Manager or Cisco Unified Communications Manager Express when the user logs in.

IDC DIALER USERNAME

No

Cisco Unified Communications Manager or Cisco Unified Communications Manager Express end user name that is configured for the user.

IDC DIALER PASSWORD

No

Cisco Unified Communications Manager or Cisco Unified Communications Manager Express end user password that is configured for the user.

DESCRIPTION

No

Description of the user.

ADDRESS LINE 1

No

Street address of the user.

ADDRESS LINE 2

No

Additional street address information

CITY

No

City of the user.

STATE

No

State or province of the user.

COUNTRY

No

Country of the user.

ZIP

No

Zip code or postal code of the user.

EMAIL

No

E-mail address of the user.

PAGER

No

Pager number of the user.

SMS

No

Short Message Service address of the user.

PHONE

No

Telephone number of the user.

TEMPLATE USER NAME

No

Cisco IPICS user name of a user to serve as a template for the new user. Various Cisco IPICS configuration option settings for the template user are applied to the user that you are adding.

For more information, see the "User Template" section.

OPSVIEW NAME

No

Name of an existing opsview to which the user will belong.

This value is ignored if you enter a value in the TEMPLATE USER NAME field.

LOCATION

No

Name of an existing location with which this user should be associated.

This value is ignored if you enter a value in the TEMPLATE USER NAME field.


User Template

The TEMPLATE USER NAME field in a CSV input file lets you designate an existing Cisco IPICS user to serve as a template for a new user. When you enter a user name in this field, various Cisco IPICS configuration option values for that user are applied to the user who is added to Cisco IPICS. Table 3 describes these options.

For more information about these options, see Cisco IPICS Server Administration Guide and Cisco IPICS Dispatch Console User Guide.

Table 3 Configuration Options from a Template User that are Applied to a New User 

Option
Description

Advanced IDC Permissions

Enables channel multi-select for voice and tone transmissions, alert tones transmissions, DTMF tones transmissions, and all talk channel transmissions for a Cisco IPICS Dispatch Console user

Allow Complex Key Settings

Allows a Cisco IPICS Dispatch Console user to configure keyboard hot keys (key assignments) for individual PTT buttons and for the All Talk button

Allow Latch

Allows a Cisco IPICS Dispatch Console user to use the latch functionality to lock in a channel

Allow Secure Channel Patch

Allows a Cisco IPICS Dispatch Console to patch a secure channel to a channel, incident or VTG

Disable Audio

Disables the microphone and speaker on the Cisco IPICS Dispatch Console of the user

Listen Only

Disables the transmission of audio from the Cisco IPICS Dispatch Console, Cisco Unified IP Phone, and dial-in phone of the user

Location

Cisco IPICS location with which the user is associated

Ops View

Ops view to which the user belongs

User Channel

PTT channel with which the user is associated

User Group

User group or user groups of which the user is a member

User Incident

Incident with which the user is associated in the Cisco IPICS Dispatch Console

User Policies

Policies with which the user is associated

User Radio

Radio or radios with which the user is associated

User Role

Cisco IPICS role of the user

VTG

VTG or VTGs in which the user is a participant


Import Summary

When the bulk users import process completes for a CSV file, an LDIF file, or a direct LDAP import, the system displays a summary of the import transaction.This section describes each of these summaries.

When the import process completes for a recurring LDAP import, the system generates a log file that contains the summary of the import transaction as described in the "Log File" section.

CSV File Import Summary

Example 2 shows a sample import summary for a CSV file.

Example 2 Bulk Users Import Summary for a CSV File

INFO    : Estimated import runtime is 1.0 minute(s)
INFO    : Parse and validate input records
INFO    : Import records into IPICS database
INFO    : Generate import statistics
 
   
 
   
SUMMARY
================================================
Input filename                                  : bulk_upload_random_users.csv
------------------------------------------------
# records in file                               : 29
# comment records skipped                       : 6
# data records                                  : 23
# invalid login name                            : 4
# invalid user first/last name                  : 0
# invalid user password                         : 0
# invalid Cisco Unified IP Phone Digit ID       : 0
# invalid Cisco Unified IP Phone Digit Password : 0
# invalid IDC dialer phone number               : 0
# invalid IDC dialer username                   : 0
# invalid IDC dialer password                   : 0
# invalid street address                        : 0
# invalid city/state/country/zip                : 0
# invalid email                                 : 0
# invalid pager                                 : 0
# invalid SMS                                   : 0
# invalid phone                                 : 0
# invalid opsview                               : 0
# invalid location                              : 0
# invalid template login                        : 1
# user login already exist                      : 0
# dial login already exist                      : 0
# duplicate login name in file                  : 2
# duplicate dial login in file                  : 0
# new records to be imported                    : 16
# new records imported                          : 16
------------------------------------------------
Results
------------------------------------------------
ERRORS FOUND
- See ipics_import_users.ipicsadmin.rejected.txt for records rejected
- See ipics_import_users.ipicsadmin.accepted.txt for records accepted
 
   
 
   
=======================================================
=     IMPORT ENDED AT Mon Mar 12 23:20:32 GMT 2012    =
=======================================================
 
   

If exceptions occur during the import process of a CSV file, the summary includes a description of each exception. These descriptions can include the following:

# dial login already exist         : 
# duplicate dial login in file     : 
# duplicate login name in file     : 
# invalid address                  : 
# invalid city/state/country/zip   : 
# invalid digit ID                 : 
# invalid digit ID pin             : 
# invalid email                    : 
# invalid IDC dialer password      : 
# invalid IDC dialer phone number  : 
# invalid IDC dialer username      : 
# invalid LDAP opsview             : 
# invalid location                 : 
# invalid login name               : 
# invalid opsview                  : 
# invalid pager                    : 
# invalid phone                    : 
# invalid SMS                      : 
# invalid template login           : 
# invalid user first/last name     : 
# invalid user password            : 
# user login already exist         :  

LDIF File Import Summary

Example 3 shows a sample import summary for an LDIF file.

Example 3 Bulk Users Import Summary for an LDIF File

INFO    : Estimated import runtime is 1.0 minute(s)
INFO    : Parse and validate input records
INFO    : Search for IPICS users that do not exist in LDAP
INFO    : Remove IPICS users that do not exist in LDAP
INFO    : No IPICS users removed
INFO    : Import records into IPICS database
INFO    : Generate import statistics
 
   
 
   
SUMMARY
================================================
Input filename                                  : ldap.ipicsadmin.ldif
------------------------------------------------
# records in file                               : 28
# comment records skipped                       : 0
# data records                                  : 28
# invalid login name                            : 2
# invalid user first/last name                  : 1
# invalid user password                         : 0
# invalid Cisco Unified IP Phone Digit ID       : 0
# invalid Cisco Unified IP Phone Digit Password : 0
# invalid IDC dialer phone number               : 0
# invalid IDC dialer username                   : 0
# invalid IDC dialer password                   : 0
# invalid street address                        : 0
# invalid city/state/country/zip                : 0
# invalid email                                 : 0
# invalid pager                                 : 0
# invalid SMS                                   : 0
# invalid phone                                 : 0
# invalid opsview                               : 0
# invalid location                              : 0
# invalid template login                        : 0
# user login already exist                      : 0
# dial login already exist                      : 0
# duplicate login name in file                  : 0
# duplicate dial login in file                  : 0
# new records to be imported                    : 0
# new records imported                          : 0
# existing records refreshed                    : 25
------------------------------------------------
Results
------------------------------------------------
ERRORS FOUND
- See ipics_import_users.ipicsadmin.rejected.txt for records rejected
- See ipics_import_users.ipicsadmin.refreshed.txt for records refreshed
 
   
 
   
=======================================================
=     IMPORT ENDED AT Mon Mar 12 23:17:24 GMT 2012    =
=======================================================
 
   

Direct LDAP Import Summary

Example 4 shows a sample import summary for a direct LDAP import operation.

Example 4 Bulk Users Import Summary for a Direct LDAP Import

=======================================================
= LDAP IMPORT STARTED AT Mon Mar 12 23:15:53 GMT 2012 =
=======================================================
 
   
INFO    : Retrieve LDAP query parameters
INFO    : Query LDAP server ipics-ad-1.cisco.com:123
INFO    :       User ID       - test1
INFO    :       Search Base   - cn=Users,dc=ipics-ad-1,dc=cisco,dc=com
INFO    :       Search Filter - (&(objectClass=user) (department=12345))
INFO    :       29 LDAP records retrieved in /tmp/ldap.ipicsadmin.ldif
 
   
INFO    : Estimated import runtime is 1.0 minute(s)
INFO    : Parse and validate input records
INFO    : Search for IPICS users that do not exist in LDAP
INFO    : Import records into IPICS database
INFO    : Generate import statistics
 
   
 
   
SUMMARY
================================================
Input filename                                  : /tmp/ldap.ipicsadmin.ldif
------------------------------------------------
# records in file                               : 28
# comment records skipped                       : 0
# data records                                  : 28
# invalid login name                            : 2
# invalid user first/last name                  : 1
# invalid user password                         : 0
# invalid Cisco Unified IP Phone Digit ID       : 0
# invalid Cisco Unified IP Phone Digit Password : 0
# invalid IDC dialer phone number               : 0
# invalid IDC dialer username                   : 0
# invalid IDC dialer password                   : 0
# invalid street address                        : 0
# invalid city/state/country/zip                : 0
# invalid email                                 : 0
# invalid pager                                 : 0
# invalid SMS                                   : 0
# invalid phone                                 : 0
# invalid opsview                               : 0
# invalid location                              : 0
# invalid template login                        : 0
# user login already exist                      : 0
# dial login already exist                      : 0
# duplicate login name in file                  : 0
# duplicate dial login in file                  : 0
# new records to be imported                    : 25
# new records imported                          : 25
# existing records refreshed                    : 0
------------------------------------------------
Results
------------------------------------------------
ERRORS FOUND
- See ipics_import_users.ipicsadmin.rejected.txt for records rejected
- See ipics_import_users.ipicsadmin.accepted.txt for records accepted
 
   
 
   
=======================================================
=     IMPORT ENDED AT Mon Mar 12 23:16:03 GMT 2012    =
=======================================================
Log File

The Bulk Users Import command generates a log file each time it executes a recurring import. The log file is stored in the /opt/cisco/ipics/database/logs folder and is named ipics_import_users.log. This file contains the same information as the direct LDAP import summary (see Example 4).

Output Files

The Bulk Users Import command generates one or more of the following output files each time it executes. Each file is stored in the folder from which you execute the command.

Accepted file—Named ipics_import_users.ipicsadmin.accepted.txt. This file includes each record that was imported into Cisco IPICS.

Rejected file—Named ipics_import_users.ipicsadmin.rejected.txt. This file includes each record that was rejected by the import process.

Refreshed file—named ipics_import_users.ipicsadmin.refreshed.txt. This file includes records for users whose information was updated by an LDIF or LDAP import process.

Each output file is in Pipe-Separated Value (PSV) format and can be opened in Microsoft Excel by specifying the pipe character (|) as the delimiter when you open the file. These files show the records in the same format as in the input file, with the following fields added to the beginning of each record:

REASON—In the Accepted file, shows "RECORD IMPORTED." In the Rejected file, shows the reason that a record was rejected.

REF #—Internal reference number.

Importing Rejected Records

If the Bulk Users Import command generates a Rejected file, you can perform the following procedure to import the rejected records:

Procedure


Step 1 Use Microsoft Excel to open the ipics_import_users.ipicsadmin.rejected.txt file.

Make sure to specify the pipe character as the delimiter when you open the file.

Step 2 Correct the issues that are reported in the REASON field for each record.

Step 3 Delete the REASON and the REF # columns from the spreadsheet.

Step 4 Use the Save As command in Excel to save the file as a CSV (Comma delimited) type.

Step 5 Use the Bulk Users Import command to import this CSV file.


Configuring LDAP Users Import Options

Using the Bulk Users Import command with the --ldapimport_config option lets you view and update LDAP import configuration options, which control several aspects of the direct LDAP import and the recurring LDAP import operations. When you use this option, the system displays current LDAP import configuration settings, as shown in Example 5.

Example 5 LDAP Configuration Settings

Please verify the following LDAP import settings:
---------------------------------------------
 
   
LDAP Server Name         : ldap.mycompany.com
LDAP Server Port         : 389
LDAP Search Base         : OU=active,OU=employees,OU=people,O=mycompany.com
LDAP Search Filter       : (& (objectClass=user) (|(departmentNumber=709394) 
(deparmentNumber=005780)))
LDAP Login Identifier    : uid
Default IPICS Opsview    : my_ldap_enabled_opsview
 
   
LDAP Query User ID       : readonly_LDAP_user
LDAP Query User Password : ********
 
   
---------------------------------------------
 
   
Would you like to change any of the value(s)?: (y/n)
 
   

To change any of these LDAP configuration settings, type y and press the Enter key. Then, follow the on-screen prompts to enter new values. The system prompts for a new value for each configuration item in sequence. If you do not want to change a value, press the Enter key without entering a new value. When prompted, type y and press the Enter key to exit and save your changes, or type n and press the Enter key to exit without saving your changes.

Table 4 describes the LDAP import configuration options.

Table 4 LDAP Import Configuration Options 

Option
Description

LDAP Server Name

Hostname or IP address of the LDAP server.

LDAP Server Port

Port number that the LDAP server uses for requests.

The port must support non-SSL encryption.

LDAP Search Base

Distinguished name of the search base object. Only users that are under this search base object are imported.

LDAP Search Filter

Search criteria for finding users within the search base object.

LDAP Login Identifier

LDAP login ID identifier column name.

Default IPICS Opsview

Name of the ops view to which users will belong after they are added to Cisco IPICS.

This ops view must exist and the Use LDAP Authentication option must be enabled for it in the Cisco IPICS Administration Console before you perform a direct LDAP import or recurring LDAP import operation.

LDAP Query User ID

Existing LDAP user ID that is used to query records in the LDAP server.

LDAP Query Password

Existing LDAP password that is used to query records in the LDAP server. The system encrypts this password.


Bulk Users Remove Command

The CLI Bulk Users Remove command, ipics_remove_users, lets you remove from Cisco IPICS a designated user or users that are defined in any of these input files:

A CSV file, including a CSV file that you used with a previous execution of the Bulk Users Import Command

An LDIF file, including an LDF file that you used with a previous execution of the Bulk Users Import Command

An Accepted file that was generated by a previous execution of the Bulk Users Import command

A Refreshed file that was generated by a previous execution of the Bulk Users Import command

The Bulk Users Remove command also lets you resolve user data inconsistencies that occur due to an interruption of the bulk users import process.

By using the most recently generated Accepted or Refreshed file as the input file when you run this command, you can conveniently reverse the last bulk users import procedure that was performed.

The Bulk Users Remove command immediately removes each designated user, regardless of the current state or association of the user, unless the user has the Cisco IPICS All or System Administrator role.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_remove_users{--user user_name |--csv CSV_file |--pipe PSV_file |
--ldif LDIF_file --login_identifier identifier |--repair}

Syntax Description

--user

Removes one designated user.

user_name

Name of a user to remove.

--csv

Removes the users that are defined in a CSV input file.

CSV_file

Name of the CSV input file that defines the users to remove.

The file must adhere to the guidelines that the "CSV Input File" section describes.

Include the path if the file is not in the current folder.

--pipe

Removes the users that are defined in a PSV input file.

PSV_file

Name of the pipe delimited file that defines the users to remove. The file must be either the Accepted file or the Refreshed file that is generated by the Bulk Users Import command. See the "Output Files" section for more information.

Include the path if the file is not in the current folder.

--ldif

Removes the users that are defined in an LDIF input file.

LDIF_file

Name of the LDIF file that specifies the users to remove.

Include the path if the file is not in the current folder.

--login_identifier

Indicates that the following value is the name of the LDAP column that identifies the login IDs of users.

identifier

Name of the LDAP column that identifies the login IDs of users.

--repair

Resolves user data inconsistencies that occur due to an interruption of the import process.


Remove Summary

When the users remove process completes, the system displays a summary of the operation. The remove summary shows the following information, as applicable:

Names of users that were not removed and the reasons that they were not removed

Names of users that were removed

VSOM Import Command

The CLI VSOM Import command, ipics_import_vsom, lets you add to Cisco IPICS links to all public and archive video feeds that are configured in VSOM 6.3.x. The links are added in bwims format, in which each link begins with bwims://.

This command also lets you activate or deactivate a recurring VSOM import process that adds links to these video feeds at regular intervals.

The following guidelines apply to this command:

The links are not displayed in the IPICS Administration Console, but you can associate any link with an incident by using the Cisco IPICS Dispatch Console.

The links that you add are associated with the System ops view by default.

If the designated Cisco VSOM server is unavailable, the import process aborts.

Existing Cisco IPICS links to VSOM public and archive video feeds are deleted from Cisco IPICS if they are not included in the import data. This situation typically occurs if video feeds are deleted from VSOM after you import them to Cisco IPICS, then you perform another VSOM import operation.

The VSOM import configuration options control several aspects of the VSOM import operations. You can view and update items in this file as described in the "Configuring VSOM Import Options" section.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_import_vsom{--import |--import_on |--import_off |--import_config}

Syntax Description

--import

Adds to Cisco IPICS links to all public and archive video feeds that are in VSOM.

--import_on

Immediately adds to Cisco IPICS links to the video feeds in the VSOM server that is designated by a VSOM import configuration option and activates the automatically recurring VSOM import process.

After you activate the recurring VSOM import process, the system executes the import at 5 and 35 minutes past each hour.

--import_off

Deactivates the automatically recurring VSOM import process.

--import_config

Lets you configure a variety of options that relate to importing VSOM video links.

For detailed information about these options, see the "Configuring VSOM Import Options" section.


Import Summary

When the VSOM import process completes with the --import option, the system displays a summary of the import transaction. Example 6 shows a sample summary.

When the import process completes for a recurring VSOM import, the system generates a log file that contains the summary of the import transaction as described in the "Log File" section.

Example 6 VSOM Import Summary

=======================================================
= VSOM IMPORT STARTED AT Wed Feb  8 17:31:08 GMT 2012 =
=======================================================
 
   
------------------------
pub_feeds
------------------------
# rows to be synced: 151
 
   
bwims://10.100.100.30/p_SD2500_1
bwims://10.100.100.30/p_SD4300-32_1
bwims://10.100.100.30/p_SD4300-33_1
bwims://10.100.100.30/p_SD4300-34_1
bwims://10.100.100.30/p_SD4300-35_1
bwims://10.100.100.30/p_axis3301p
bwims://10.100.100.30/p_axis3301p_0
bwims://10.100.100.30/p_4500V_1
...
 
   
------------------------
pub_archives
------------------------
# rows to be synced: 0
Log File

The VSOM Import command generates a log file each time it executes a recurring import. The log file is stored in the /opt/cisco/ipics/database/logs folder and is named ipics_import_vsom.log. This file contains the same information as the direct VSOM import summary (see Example 6).

Configuring VSOM Import Options

Using the VSOM Import command with the --import_config option lets you view and update VSOM import configuration options, which control several aspects of the VSOM import operations. When you use this option, the system displays current VSOM import configuration settings, as shown in Example 7.

Example 7 VSOM Import Configuration Settings

Please verify the following LDAP import settings:
---------------------------------------------
 
   
VSOM Server Name         : 10.100.100.10
Default Opsview          : SYSTEM
 
   
VSOM Query User ID       : public
VSOM Query User Password : ********
 
   
---------------------------------------------
 
   
Would you like to reset the value(s)?: (y/n)
 
   

To change any of these VSOM configuration settings, type y and press the Enter key. Then, follow the on-screen prompts to enter new values. The system prompts for a new value for each configuration item in sequence. If you do not want to change a value, press the Enter key without entering a new value. When prompted, type y and press the Enter key to exit and save your changes, or type n and press the Enter key to exit without saving your changes.

Table 5 describes the VSOM import configuration options.

Table 5 VSOM Import Configuration Options  

Option
Description

VSOM Server Name

Hostname or IP address of the VSOM server.

Default Opsview

Name of the ops view to which video links will belong after they are added to Cisco IPICS.

This ops view must exist in the Cisco IPICS Administration Console before you perform a VSOM import operation.

VSOM Query User ID

VSOM User ID used for querying Cisco VSOM public views.

This value must match the user ID for querying public views that is configured in VSOM.

VSOM Query User Password

User password used for querying Cisco VSOM public views. The system encrypts this password.

This value must match the user password for querying public views that is configured in VSOM.


VSOM Remove Command

The CLI VSOM Remove command, ipics_remove_vsom, lets you remove from Cisco IPCIS links that reference VSOM public and archive video feeds.

Executing this command immediately removes from Cisco IPICS all designated links, regardless of their current states and assignments. This command does not affect video on the VSOM server.

For general information about running a CLI command, see the "Using the CLI Commands" section.

Command Syntax

ipics_remove_vsom{--all |--before YYYYMMDDhhmmss |--after YYYYMMDDhhmmss}

Syntax Description

-all

Removes all VSOM video links from Cisco IPICS.

--before

Removes from Cisco IPICS all VSOM video links that were modified on or before the designated date and time.

YYYYMMDDhhmmss

Date and time at or before which video links to remove were modified.

Enter this value as a 14-digit string that represents year, month, day, hours, minutes, and seconds.

--after

Removes from Cisco IPICS all VSOM video links that were modified on or after the designated date and time.

YYYYMMDDhhmmss

Date and time at or after which video links to remove were modified.

Enter this value as a 14-digit string that represents year, month, day, hours, minutes, and seconds.


Remove Summary

When the VSOM remove process completes, the system displays a summary of the operation. The remove summary shows the links that were removed.