README

这个PHP库使用Sonar API将标准格式数据导入Sonar。

这个工具相当技术性。如果你不熟悉这个工具，请联系onboarding@sonar.software寻求帮助。

安装

注意

此工具已在Linux（特别是Ubuntu）上构建和测试，尽管它在任何Linux发行版上可能也能正常工作，但尚未在其他操作系统上进行测试。

导入器是用PHP编写的。尽管此导入器应与PHP 5.5+兼容，但我建议使用PHP7以获得最佳性能。如果你使用的是Ubuntu 16.x，则默认已安装PHP7。

设置

你可以通过三种方式安装此工具 - 克隆存储库、使用Composer并通过Packagist下载，或者点击这里，解压它，然后进入文件夹。我建议使用git或Composer进行安装，这样你可以轻松地保持它是最新的。

导入器使用Redis进行缓存，你需要安装Redis服务器。你可以在Ubuntu上通过输入sudo apt-get install redis-server来安装它。

要设置导入器以供使用，在importer目录中创建一个.env文件，方法是将.env.example文件复制。将URI、USERNAME和PASSWORD值修改为匹配你的Sonar实例。用户名和密码必须是对具有适当API权限的用户账户的访问权限。最安全的选项是使用“超级管理员”用户。当运行导入器时，它将在当前目录中查找.env文件，所以确保你在运行时位于与.env文件相同的目录中。这允许在必要时由多个用户使用该工具。

模板

templates文件夹包含描述应使用此工具导入数据的CSV格式文件的电子表格。每个电子表格都有一个包含一些基本说明的选项卡和一个包含CSV格式的选项卡。大多数格式选项卡中的列都有更详细说明的注释。当导出CSV时，它们应该是逗号分隔的，并且字符串应被双引号包围。

下面描述的所有导入器都使用来自templates文件夹的模板。

使用导入器

第一步

1. 在导入之前，我们也强烈建议您在“财务”>“计费”>“配置”下禁用“每日计费”。您不希望账户在导入完成并验证之前就被计费！
2. 创建所有必需的服务、税费、地址类型、组、状态等。导入器的目的是导入大量数据——账户、联系人、信用卡等。导入器的一些部分将需要您引用账户的状态或地址的类型。这些需要在您开始之前创建。我强烈建议创建一个小的脚本通过API构建这些项目，这样您可以在需要的情况下轻松重置系统。有一些导入器设置为导入基本服务结构和这里提到的其他一些项目，但手动完成通常更容易。
3. 如果您正在导入支付方式，请在Sonar中设置您的支付处理器信息。导入信用卡或电子支票账户需要有效的支付处理器。
4. 在“财务”>“计费”>“默认设置”下设置您的计费默认值。在导入之前将这些设置为正确值将有助于避免账单日期设置得太远的错误。
5. 仔细检查您的数据——导入CSV（数据在错误的列中）可能产生非常意外的后果。例如，将账户状态ID放在先前余额列中肯定不会按您期望的方式执行。
6. 在导入之前使用地址验证器验证所有包含地址的CSV文件。这一步非常重要，因为没有经过正确验证的地址，您几乎肯定会遇到许多失败。

CSV格式化

您的CSV文件应该是逗号分隔的。每个列都必须包含，即使它是可选的。一个可选列可以不输入任何数据。字符串应该用双引号括起来，并且字符串中的双引号应该用反斜杠转义。

如何使用

要使用导入器，从您解压缩导入器所在的目录中运行命令行工具importer，输入php importer。从菜单中选择一个选项，您将需要进一步的信息。确保在导入之前通过“验证地址”功能运行您的账户CSV！

导入器输出

假设没有发生致命错误（这将引发异常），导入器将日志写入log_output文件夹。该文件夹将包含失败和成功日志文件，将报告任何失败，以及成功。除非失败日志文件完全为空且“失败”计数为0，否则导入不是完全成功的！每个功能也会提供包含失败的失败日志文件的路径。

验证账户地址

在导入您的账户之前，验证地址非常重要。Sonar需要格式良好的地址，包括两个字符的国家代码（以及美国地址的县。）您可以在运行导入之前将您的账户导入文档输入地址验证器。这将尝试验证每个地址，对任何坏地址返回失败，并对任何可以验证的地址返回一个新的CSV文件。

如果任何地址被拒绝，这意味着无法进行地理编码。您必须在将它们导入Sonar之前手动修复这些地址。逐个检查失败日志中的条目，对其进行清理，然后将其添加到验证列表中。然后，您可以将验证列表输入到账户导入器中。

在Sonar中，地址的要求包括line1值、城市、州、邮编、国家以及县（如果地址位于美国，并且州有县的话）。您可以从Sonar API的/api/v1/_data/counties/{state}获取有效县列表，其中{state}是两个字符的州简称（例如WI, AZ）。如果某些地址无法验证，反复运行验证器是没有意义的 - 请手动修复它们，然后继续账户导入。请注意，地址验证器中的任何失败都会导致账户导入器的失败，因此请确保首先执行此步骤！

请注意，地址验证结果会缓存一段时间，这样运行地址验证器就会快得多。但是，如果您进行需要清除缓存的重大更改，您可以在工具菜单下进行操作。